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Introduction to Odd Job 



OddJob (OJ) is an interpreter for programs written in the OJ script language; this manual 
describes the OJ language and the features of the OJ interpreter. The purpose of OJ is to 
make life easier for users of the OS-9/68000 and CD-RTOS operating systems. 

You are, no doubt, already familiar with the idea of a "shell script," which is simply a list 
of program invocations (tasks) for the computer to do, in the order in which they appear in 
the script, together with certain directives to the shell program itself. When the shell program 
interprets a "shell script/* it simply reads the shell script file line by line, and executes what 
is written on each line just as if it had been typed at the shell prompt. (If you are not 
familiar with the shell or with the concept of a shell script, it would be a good idea for you 
to read about the shell program in your OS-9/68000 operating system manual.) If you are 
familiar with the MS-DOS world, it might help you to know that a shell script is very much 
like a .BAT file in DOS. 

OJ is not currently configured as a shell; it does not offer an interactive shell prompt to the 
user. Instead, it is a programming language which greatly expands the number and complexity 
of tasks possible to have accomplished automatically under the OS-9 operating system. It 
also offers special facilities which no DOS programming language can offer, which take ad- 
vantage of OS-9*s real-time multitasking and true piping capabilities. OJ perhaps most closely 
resembles the Unix C-Shell script language, but it includes within itself several of the features 
of several other Unix utilities, such as chat and awk. OJ's handling of variables and its 
string-processing facilities are especially awk-like, with its arbitrarily associative variable lists, 
sprintf, fprintf, and substring commands, and its index () function. Pro- 
grammers who are already familiar with both the C language and awk will find OJ particularly 
easy to learn. 



FLOW OF CONTROL 



The OJ interpreter supports very generalized structured flow-of-control commands. These in- 
clude if, else, endif, switch, case, default, break, loop, and con- 
tinue, which work very much like their counterparts in the C language. It also supports 
an unstructured goto command. Subroutine calls and returns can be made with the in- 
clude, argumented do, and return commands. 
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STRING MANIPULATIONS 



The OJ string manipulation command set includes set (which offers several string processing 
options), arraytok, replace, alphameric, substring, and sort. 



CALCULATIONS, VARIABLES AND FUNCTIONS 



OJ supports double-precision floating-point calculations, n-dimensional arrays of variables, and 
the same set of arithmetic and logical operators as is found in the C language. Special 
functions available within calculational expressions include index{), namecmp ( ) 
strcmpO. length() t rand() f charval(), min(), max(), devrdy()' 
oct2dec(), hex2dec (), frac(), int(), isdir(), isfile(), 
isreal { ) , lvarnum ( ) , and gvarnum ( ) . There are two classes of user variables: 
local (to the current script) and global. Random numbers, arrays of repeatable and non-re- 
peatable random numbers, and automatic and manual random-number seeding are provided. 
Convenient means are provided (vsave and vrestore) to save and restore the contents 
of variables to and from named disk files. 

There are ; ( al system-reserved pseudo-variables and arrays of pseudo-variables: ex- 

itstat, argc, e_banner, pwd, systime, systimef, procid, userid, 
sendbuf [], reply [], ereply[], qreturn, stderr, stdout, argv[], 
curscript, LV_NAME[], GV_NAME [ ] , LV_CONT [ ] , GV_CONT[], LVARS, 
and GVARS, and pseudo-constants used for identifying and interpreting error condition- 
s' . . , e_msg []. 



INPUT/OUTPUT 



There is a convenient (and very C-likf) set of input/output commands, including fprintf, 
openf lie, closef ile, readf ile, writef ile, seekf ile, and tellf- 
ile. To write to the console, fprintf $stdout or fprintf $stderr are 
normally used. 



SOCKET INTERACTIONS 



With its unique "socket-interaction" command set, OJ is able to support scripts which are 
intended to simulate the behavior of an interactive user of one or more simultaneously-active 
processes. Such processes can be running both on (he local computer and on remote com- 
puters. For example, a script can be used to operate a local interactive process which would 
otherwise require tedious or repetitive attention from a human operator, and it can be written 
in such a way as to occasionally consult another process (e.g., an interactive Prolog environ- 
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ment) running locally or remotely. The socket interaction command set includes 
set_waits, set_send_delay, ignore, send, socket, set_mbf (set 
match buffer), password, show_mbf s (show match buffers), strip_msb_on, and 
stnp_msb_of f. For debugging socket interactions, verbose_on and ver- 
bose_of f commands are provided. 



REDIRECTION TO AND FROM OJ VARIABLES 



If the interactive control offered by the socket interaction commands is not needed, the re- 
direct command allows processes to be launched in such a way that their standard input 
and output streams are directed from and/or to OJ variables. 



DEBUGGING AND OPTIMIZATION FACILITIES 



There is an interactive script debugger, with commands for setting and killing breakpoints 
listing files, inspecting and setting variables, displaying status, etc. 

In addition to the debugger, there is a debugging command set which includes 
debug_on(_of f ) , show_vars , show_labels , echo_on (_of f ) 
show_tokens_on(_of f ) , show_comlines_on ( off) and 

sys_exec_on (_of f ) . 

Elapsed time measurement commands include marktime, dif ftime, and Julian. 
Other miscellaneous commands include chd, chx, set_prior(ity), and wait. 



SYSTEM REQUIREMENTS 



As supplied for use with MC680O0-based systems, the OJ executable module is about 85 
kilobytes in size. Each OJ process requires about 12 kilobytes of RAM in order to be 
launched; the amount of memory used after that depends entirely on ho martv variables and 
labels are used, and how much data each variable mus*. accommodate. There is no hv'nt-m 
limit on the number or size of veriables thai CJ can s'-Dort. (The memory allocated to a 
variable can be recovered for re-use by OJ via Jie ur.:3t comnarcV 
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Installation 

Any last-minute notes about installation and operation of OJ are in the README file on 
your OJ disk. Read it first. 

Your installation disk has an OJ script on it which will assist you in installing OJ on your 
OS-9/68000 computer system. It's easy to do; merely execute the installation script and an- 
swer the questions it asks you interactively. 

To execute the installation script: 

(STEP 1) Log into your system as the super-user (user number 0.0). 

(STEP 2) Insert the installation disk into your floppy disk device (e.g., /d0). 

(STEP 3) Change your current directory to the root directory of that floppy disk device: 

OS-9: chd /d0 
(STEP 4) Load oj: 

OS-9: load -d oj 
(STEPS) Execute the install script: 

OS-9: oj install 

From here on, you will be asked several questions about where you want various things to 
be put on your hard disk, etc. When these questions have been answered, the install script 
will handle the tedium of installing the program. 

The install script will copy the OJ program itself to the directory you specified, create a 
default directory for OJ scripts, copy some sample scripts to that directory, edit your .login 
file so as to set the OJ_PATH environment variable, etc. 

Alternatively, if yo?; do not choose to use the Somatic installation script, you may install 
OJ yourself as follows: 
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(1) Copy OJ to a directory of executables. Having copied OJ to its new directory, make 
sure OJ's execute permissions are set correctly, and make sure your .login file (see 
the OS-9 manual regarding the /dd/SYS/password file) sets the PATH shell environ- 
ment variable in such a way that OS-9 will look in that directory for OJ when it is 
invoked. (Here at Technoteacher, Inc., we always place executables not supplied with 
the OS-9/68000 operating system in a directory called /dd/USR/CMDS. In fact, we 
put everything not supplied by Microware in /dd/USR, because that enables us to 
update the entire operating system without first having to extract from the old version 
and re-insert into the new version all the files that were not supplied by Microware.) 

(2) Copy all the scripts from the /floppy disk devtce/SCRIPTS directory to a directory on 
your hard disk which you have set aside for such scripts. At Technoteacher, Inc., 
we use /dd/USR/SCRIPTS for this purpose. 

(3) Copy the contents of the /floppy ditik device/DOC directory to your documentation 
directory. At Technoteacher, we use /dd/USR/DOC for this purpose. If disk space 
is in short supply, you may wish to copy only the ojdb.doc file, which is automatically 
read when the ? debugger directive is issued. 

(4) Edit your .login file in such a way that the OJ_PATH shell environment variable is 
set to the full pathnames of the directories in which you wish OJ to look for exe- 
cutable scripts. Presumably, one of these will be the one you used in step 2, above. 
See Section 3 of this manual for more information about OJ_PATH. If the OJ.PATH 
shell environment variable has not been set, OJ will look first in the current data 
directory, and then in /dd/USR/SCRIPTS; it is just as if there were the following line 
in your .login file: 

setenv OJ_PATH .: /dd/USR/SCRIPTS 

(5) Edit your .login file in such a way that the OJ_DOC shell environment variable is 
set to the full pathname of the directory where you put all the OJ documentation. 
For example, you might insert the following line: 

setenv OJ_DOC /dd/USR/DOC 

However, if you put the documentation in /dd/USR/DOC, it is unnecessary to set the 
OJ _DOC environment variable at all. OJ will look there by default if the OJ JX)C 
shell environment variable has not been set. 



Invocation of O J 

Normally, one invokes OJ as follows: 

OS- 9: oj (opts) namejofjcrxpt (args Jo script) (opts) 

Options governing the operation of OJ all begin with two hyphens (--); this allows OJ 
scripts themselves to have options that begin with a single hyphen. However, like most OS-9 
utilities, 

OS-9: oj -? 
will cause a usage statement to be displayed. OJ*s options are: 

- ? Show an OJ invocation line synopsis. 

--b Specify the size (in bytes) of the buffer to be used for reading the script 

itself and all scripts done or included by the script. The minimum 
buffer size is 512 bytes. The purpose of the --b option is to allow you to 
minimize memory usage when running large and/or highly recursive scripts, 
at some sacrifice in execution speed. In the absence of a --b option, each 
script will get a buffer just big enough to accommodate the entire script; this 
reduces execution time by minimizing disk accesses, especially during itera- 
tions of large loops. 

/ 
--d Operate in debug mode. See Section 11. 

--e Force echoing of each executable lir-^ to the console, overriding any 

echo_of f. (See the discussion of the 3cho_on command.} 

--q Prohibit verbose output, cyvtxidn? any v^,rbose„cr. (See 'he discussion 

of socket, send, and relatec comir-~ds." 
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Force verbose output, overridrng sny verbcse_of L. (See the discussion 
of socket, send, and relate^ commands.) Also affects the wait com- 
mand. 
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--x Prohibit system command execution, overriding any sys„exec_on. (This 

prevents all separate programs normally invoked by the script from actually 
being invoked.) 

OJ may be instructed to look for scripts in any directories. Use the "setenv" command at 
an OS-9 shell prompt (it is best to do this in your /dd/startup or your own .login file): 

OS-9: setenv 

OJ_PATH. :/hO/usr/scripts:/hO/usr/srn/scripts 

The above setting of the OJ_PATH shell environment variable causes OJ to look first in the 
current working (i.e., data) directory for scripts, then in /hO/usr/scripts, and finally in 

/hO/usr/srn/scripts. 

If you don't do a "setenv OJ_PATH ... ," OJ'will look first in the current working directory, 
and then in /dd/usr/scripts. Of course, if you provide the full pathlist of the script, beginning 
with a slash and a device name, that will be the only script file OJ will attempt to open. 

Alternatively, you may set a local and/or a global variable within an OJ script, which will 
override the effect of any environment variable you set with setenv at an OS-9 prompt: 

# inside a script now 

set OJ_PATH = . . :/hO/usr/scripts: /hO/usr/srn/scripts 



Execution of OJ Scripts 



The OJ interpreter executes actual command lines as they appear in a given ,oj script. There 
is exactly one command at the beginning of each line. 

For each line, the interpreter does the following four things in order: 

(1) tokenizes the command line; 

(2) performs macro substitution; 

(3) performs variable substitution; 

(4) executes the command. 



STEP 1: TOKENIZATION OF THE COMMAND LINE 



The command line is scanned for its "tokens," the smallest units meaningful to the interpreter. 
Tokens are separated by whitespace (i.e. any number of spaces and/or tabs). To include 
whitespace characters in a token, surround the entire token with double quotation marks. Dou- 
ble quotation marks which surround tokens are discarded. To include a double quotation 
mark within a token, precede it with a backslash (i.e., \"). 

# example showing tokenization 

tokenO tokenl "This is all token2 " 

tokenO "This \"token\" contains double quotation 

marks n 



STEP 2: MACRO SUBSTITUTIONS 



The macro substitution feature of OJ provides the only way to create multi-token arguments 
with a single symbol. To set up a macro, first set a variable to the string you don't want 
to write repeatedly: 

# set the variable . "my_error" 
sprint f ny_error \ 

"fprintf $stderr \ H this program aborted because %%s\n\"" 

Now, $my_error will contain: 
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fprintf $stderr "this program aborted because %s\n" 
Thereafter, the command line: 

$ (my„error) »i blew it" 
will (before it is executed) Somatically become: 

fprintf $stderr "this program aborted because %s\n" "I blew it" 

Note the use of parentheses in "$ (my_error) ." The parentheses indicate to the inter- 
preter that macro substitution must be done. Note that in the example above, a single token, 
$ (my_error) , became three tokens as a result of macro substitution. 

/ 
Multi-line macros are not supported. The entire macro must take place on one and only one 
line. (It will not do any good to use a \ character in your efforts to make a longer line.) 
Neither recursive macros nor argumented macros are supported. 



STEP 3: VARIABLE SUBSTITUTION (see also Section 6) 

Tokens that begin with $ are assumed to consist entirely of a $ immediately followed by 
the name of a variable to which a value has already been assigned. (Any command that 
assigns a value to a variable will create that variable if it does not already exist.) In this 
third step, whenever encountered, such a token is replaced by the content of the variable 
whose name follows the $ 

A variable name may be any length, and must begin with an alphabet character of either 
upper or lower case; thereafter it may contain any combination of the following characters 
only: any alphabet characters of either case, any numeric characters (0 through 9), periods 
(.), underscores (_), and left and right square brackets ([ and ]). 

The square brackets are treated as array index operators (see Section 6 for a discussion of 

arrays). 

The contents of all variables are actually strings, even if their content is numeric. If the 
variable name given after a $ does not exist, OJ will abort (or, if OJ was invoked with the 
--d option, give the user an OJdb: [interactive debugger] prompt); therefore, you must 
always be sure to set a variable to some (any) value prior to the time OJ encounters it with 
a $ before it. If the variable does exist, the content of that variable (a string) will be 
substituted for the token. 

Because r~nain commands must perform character substitutions (see Section ? N «heir variable 
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substitutions are not done in this step 3; rather, they are done later during execution of the 
command-specific software in the interpreter. Generally this doesn't make any difference, 
except that it does give you a way to avoid variable substitution altogether: if you are using 
a backslash-interpreting command and you must begin a token with $, precede the $ with 
a backslash. 

For more information about variable substitution, see Section 6. 

There are two classes of variables in OJ: local (i.e. local to the current script) and global 
(i.e., available to all called and calling scripts). For more information, see the discussions of 
the local, do, return, and include commands. 



STEP 4: EXECUTION OF THE COMMAND 



Generally speaking, a particular portion of the interpreter software is associated with each 
particular command in the OJ language, and this portion is called only after all three steps 
outlined above are completed. 
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Miscellaneous Syntactical Features 



COMMENTS 



Any token beginning with a # is ignored, as are all following tokens on that file line. 
Therefore, comments are preceded by a #. 



IDENTIFIER 



All OJ scripts must begin with a comment line; the first character of any OJ script must be 
#. This is to protect against having a disk savaged by OJ inadvertently executing something 
other than an OJ script. 



CONTINUED LINES 



A command line may be continued on the next file line, if it gets too long, by ending the 
line to be continued with a token consisting of a single backslash. A single command line 
can thus extend over any number of file lines. For example: 

# WILL WORK: 

set somevar = "This will work just fine " \ 
"because I am breaking the line " \ 
"on token boundaries." 

# WON'T WORK: 

set somevar = "This will n<pt work because \ 
I am attempting to break up a single token \ 
into several lines." 



WHITESPACE 



Tab characters and spaces that do not occur within tokens are regarded as whitespace and 
are discarded. It is perfectly ok to use any amount of whitespace at the beginning of any 
command line, as well as between any two tokens. This makes it easy to show program 
structure, for example, by indenting the commands within an if, loop, or switch re- 
gion. It is also a good practice to indent continued lines to emphasize the fact that they are 
continued, as was done in the example above. 
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Variable Substitution 



There are really two distinct types of variable substitution at work in OJ. The main type, 
"dollar substitution," is used for all commands, period. The other type, "automatic substitu- 
tion," works only in calculational expressions ("calc expression" or "calc exp"), which are 
only found in certain parts of if, calc, loop, return, exit, and setprior 
commands. What makes things confusing, perhaps, is that both dollar and automatic substi- 
tution are at work in the commands that can contain calculational expressions. 

Dollar substitution is made available to the programmer via the $ character. As the inter- 
preter executes a script, each line of code undergoes tokenization, macro substitution, and 
then dollar substitution. In dollar substitution, if any token on the line begins with the $ 
character, that entire token is replaced by the entire contents of the variable whose name 
follows the $. At this point, the interpreter does not yet care which command is to be 
executed (i.e., what the first token on the line is); therefore all commands, including the 
calculational commands, are subject to dollar substitution. 

The second form of variable substitution, automatic substitution, is available without the use 
of the $ character. It only occurs in calculational expressions, however, and calculational 
expressions are found in only the following commands: if, calc, loop, exit, re- 
turn, and setprior. 

Here is a complete list of the places where calculational expressions can appear: 
if calc exp 
calc var = calcjexp 

loop label ; var = calcjexp ; calcjexp ; var = calc exp 
exit calcjexp 
return calcjexp 
set_prior calcjexp 

Please note that no calculational expression can be understood by the interpreter unless it 
appears in one of the above places. For more information on calculational expressions see 
Section 8. 

If the command line turns out to be a calculational command, the software which is peculiar 
to each such command (and which comes into play only after the dollar substitutions have 
occurred— see Section 4) begins by concatenating all the tokens that appear in the expression. 
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Section 7: VARIABLE SUBSTITUTION 

In the example: 

calc z = 12 / 14 - (34 * z) 

the expression on the right side of the assignment operator token (=) will be concatenated 
into: 

12/14-(34*z) 

Then, any strings not recognized as real numbers (such as z, above) will be assumed to be 
variable names, and the values of those variables will be substituted. Thus, the $ is not 
needed in front of any variable name that occurs in a calculational expression. The value 
will be substituted automatically. 

If the value of z in the example above is 2*9, then, the expression will become: 

12/14-(34*29) 

Finally, the entire expression will be evaluated arithmetically, and the resulting real number 
will become a string of decimal digits (with, in this case, a decimal point). After the calc 
is executed, the variable z will contain this string. The only other type of character found 
in the result of an evaluation of a calculational expression is a leading minus sign (-) in the 
case of a negative number. 



SUBSCRIPTS AND ARRAY INDEXES 



Subscripts and array indexes can be arbitrary strings; they need not be integers as in many 
other computer languages. For instance, it is possible to have an ordinary array: 

z[0] 
z[l] 
z[2] 

and it is equally possible to have an array which allows a series of arbitrary strings to be 
associated with a particular variable name: 

z [george] 
z [natalie] 

z [harriet] 
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The elements of these arrays can only be accessed by using their exact names, but one may 
even have weird multidimensional arrays containing items named, for example: 

z[george[nose]] [wart [01] [itch] 

JflhtT v Xamp,C " a , !8 ht - hearted one . b «t there is plenty of serious applicability for such 
variables. You can use this feature for data structures such as this: 

loop Oend ; j = ; j < total_students ; j = j + 1 

fpnntf $stdout "student %3d" $j 

fprintf $stdout "name: %s\n" student [$j ] [name] 

fprintf $stdout "\tgpa: %s\n" student [$j ] [gpa] 

fprintf $stdout "\tsex: %s\n" student [$j] [sex] 

0end rint $Stdout " Uclass: %s\n\n" student [$j ] [class] 

It is possible to use a variable containing an arbitrary string as an array index, like this: 

set indexvar = foo # the content of indexvar is 

._ , A . , # now the string "foo". 

set x[$indexvar] = dahlia 

We have now created a variable named x[foo] and set it to the string "dahlia". 
USE OF THE DOLLAR SIGN IN ARRAY INDEX SUBSTITUTIONS " 



Note that the $ is required in any substitutions made inside square brackets (ie when vou 
use a variable as an array index). In army iridex substitutions; the $ is required reganiless 
of the particular command you are using. «egdiuiu* 

Below are illustrations of several methods that will work, and several that won't work All 
are assumed to be preceded by the following lines of code: 

Ht vroi°- i?i J T° ^Y used later as an array index. 
set y[0] - 123 # Just to create y[0] and put some 

# value in it. 

# (Note: the above two lines could have used 
ff the calc command instead of the set 

# command with no other changes.) 
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Section 7: VARIABLE SUBSTITUTION 



Now, in all the command lines below, we're trying to set the variable x to the value contained 

in the variable y [ ] . 



These methods will work: 
calc x = y[0] 

calc x = $y[0] 

calc x = $y[$z] 

calc x = y[$z] 

set x = $y[$z] 



# This will work; automatic substi- 

# tution is done by the calc com- 

# mand. 

# This will work just as well; dol- 

# lar substitution occurs before 

# the calc command ever sees it. 

# This will work; dollar substitution 

# is done before the calc command 

# ever sees it, 

# This will work; automatic sub- 

# stitdtion is done by the calc 

# command. 

# This will work. Dollar substitu- 

# tion is required because auto- 

# matic substitution is not avail- 

# able in a set. 



These methods will not work: 
set x = y [z] 

set x = y[$z] 

calc x = y[z] 



set x = $y[z] 



# This will set the variable "x" to 

# the string H y[z] B — not what 

# we're trying to do, 

# This will set the variable "x" to 

# the string "y[$z] n — not what 

# we're trying to do. 

# This won't work— z won't be sub- 

# stituted, and there is no vari- 

# able "y[zj". z won't be substi- 

# tuted because the $ is always 

# required within square brackets, 

# OJ will abort. 

# This won't work; there is no vari- 

# able called "y[z] H and OJ will 

# abort . 



Since an array index can be almost any string, it is fruitless to use a mathematical expression 
as an array index in the hope that it will be evaluated and the result will become the index 

value. 
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For example: 

set a = z [$x + 1] 
will not work. However, the following will work and will have the desired effect: 

calc y = $x + 1 # Expression evaluated here. 

# (The $ is optional- both 

# dollar and automatic sub- 

# stitution are available 

# here. ) 

set a = $z[$y] # String resulting from expres- 

# sion in the calc above is 

# now used as an array index. 



In order to test your understanding of what's going on here, it's a good idea to write a series 
of scripts using all of the above methods and showing the results. To make things easy on 
yourself, just put a show_vars command at the end of each script. 

Here is an example of a script that illustrates a few other points: 

1 show_tokens_on # This will cause the interpreter 

2 # preter to output a veritable 

3 # torrent of stuff before 

4 # executing each line. 

5 echo_on # This will cause each line to be 

6 # echoed to the screen after 

7 # dollar substitution. 

8 set z = # calc z = would have the same effect 

9 # since is a (very simple) 

10 # mathematical expression. 

11 set x[0] = george 

12 set x[z] = harry 

13 fprintf $stdout "\$x[z] == \"%s\"\n" $x[z] 

14 fprintf $stdout "\$x[\$zj == \"%s\"\n" $x[$z] 



NOTE: The backslash appears before two of the dollar signs On lines 13 and 14) to prevent 
the interpreter from attempting to perform variable substation on fhe tokens of which they 
would otherwise become the the first character. 
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The output of the above script is: 



token [0] 


: "echo on" ^ 


token [0] ■ 


. "set" 1 

" z " [ These lines result from 
"=" i show tokens_on. 
"0" ' 


token [1] : 


token [2] : 


token [3] : 


A 8: set z = ... This line is from echo_on. 


token [0] : 


"set" 


token [1] : 


"x[0] " 


token [2] : 


h __ n 


token [3] : 


"george" 


A 11: set 


; x[0] = george 


token [0] : 


"set" 


token [1] : 


"x[z] " 


token [2] 


n _ n 


token [3] : 


"harry" 


A 12: set 


: x[z] = harry 


token [ ] 


: "fprintf" 


token [1] 


. "\$stdout n 


token [2] 


: "\\\$x[z] == \"%s\"\\n" 


token [3] 


: "\$x[z] H 


A 13: fprintf 147672 \$x[z] == \"%s\"\r harry 


$x[z] == 


"harry " ... This output is from 


token [0] 


: " f print f " the first f print f. 


token [1] 


: "\$stdout" 


token [2] 


: -\\\$x[\\\$z] == \"%s\"\\n" 


token T 3 1 




A 14: fprintf 147672 \$x[\$z] == \"%s\"\r george 


$x[$z] == 


= " george " ... This output is from 



the second fprintf. 

NOTE: Quotation marks surround the control strings in the fprintf commands in order 
to allow those strings to contain spaces and yet become one and only one token. Please 
note that the quotation marks surrounding any token are stripped off when the lines are 
tokenized, as is evident if you look above at the output generated because of the show_to- 
kens_on command. When you want quotation marks to form a portion of the control 
string, precede them with backslashes. 

NOTE: When you look at the output generated by the show__tokens_on command, 
please note that each token is displayed on your screen as if it had been processed by the 
alphameric command. The single leading backslash has been converted into two back- 
slashes; otherwise the interpreter might think a single character was meant by the combination 
of the backslash and the character following it, like \n. For more information about back- 
slash interpretation, see Section 10 and the alphameric command in Sermon 11. 
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Calculational Expressions 



The expressions found in calc, if, loop, exit, return, and set_prior com- 
mands are treated somewhat differently than the arguments of other commands. Variable 
names do not have to stand alone as individual tokens, and they do not have to be preceded 
by a $; the name will always be substituted for its value (a string) whether it is preceded 
by a $ or not (except, of course, for the variable on the left side of the assignment operator 
token = ). For a discussion of this automatic form of variable substitution, see Section 7 
In OJ, calculational expressions may appear only in calc, if, loop, exit, return! 
and set_prior commands. Expressions may be of arbitrary complexity, although the 
number of levels of parenthesization is currently limited to a depth of 10. 

Operands (after variable substitution) must consist entirely of real decimal numbers The 
evaluation of a calculational expression is always a real decimal number. Logical operations 
result in (false) or 1 (true). In the absence of parentheses to the contrary, operators are 
applied in the order: 

! reverse logical value of next operand or parenthesized expression 

* multiply 

/ divide 

% mod (modulus; gives remainder after dividing the integer portion of the op- 

erand on the left side of the % by the integer portion of the operand on the 
right side of the %) 

+ add 

- subtract / 

The following logical operators always result in 1 (true) or (false). Their operands must be 
real decimal numbers (use the strcmp ( ) function to render the comparison of two non- 
numenc strings into a numeric value): 



> = 



< = 



greater than 

greater than or equal to 

less than 

less than or equal to 

equal to 

not equal to 
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The following logical operators combine multiple logical expressions: 
&& (logical AND) 

I I (logical OR) 



SPECIAL CALCULATIONAL FUNCTIONS ~ " 

Calculational expressions may contain the following special functions, whose arguments (in 
parentheses) may be strings or variable names. Enclose a string with single quotation marks 
to guarantee that it will be considered a string rather than a variable name. In order to 
specify a string which contains a single quotation mark character, precede the single quotation 
mark character with a backslash. 

charval (a) returns the integer ASCII value of the first character in a. If a 

is a variable which is empty, charval ( ) returns 0. 

devrdy {device name) returns 1 (i.e., true) if one or more characters are waiting to be 

picked up from the specified SCF device. For example, 
devrdy ( ' /term' ) can be used to test whether any keys 
are waiting to be picked up from the console. See also the 
st din and spilldev commands. 

local ctr # example 

fprintf $stdout "Press any key to continue. \n" 

spilldev /term # throw away anything 

loop ; ; !devrdy('/term') ; 

# wait for someone to type 

# something 

fprintf $stdout "%c" 7 # ring the bell 
loop 1 ; ctr = ; ctr 15 ; ctr = ctr + 1 

# 15 seconds per ring 
wait 2 # longest wait to break 

# is 2 half-seconds 
if (devrdy ( '/term' ) ) 

break 
endif 
1 

spilldev /term 

f rac (val) returns the fractional part of val. If val is 24 31 f rac ( val) 

will be 0.31. 
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gvarnum ( varname) 



returns the element number of the GV_NAME [ ] (global variable 
name) and GV_CONT [ ] (global variable content) arrays which 
corresponds to varname, if it exists, or the element number where 
varname would be if it were inserted alphabetically. You cannot 
tell whether varname exists by using gvarnum(); use 
length ( ) for that purpose. See also 1 varnum ( ) . 



set 

set 
set 
# . 
let 



set 



# example 



flower_dahlias =29 
flower_daf fodils = 34 
flow_control = $in_progress 
.other variables are set here... 
s find out the number of the 

of the variables whose 

with "flower": 



# now 



# first 

# begin 
varnum = " 



names 



set work = 



1 # create these vars now so 

# creating them later won't 

# change the gvarnum () value 

# of any other vars 
calc varnum = gvarnum ( ' flower ' ) 
substring work = $GV_NAME[$ varnum] 6 

# (there are 6 chars in "flower* 
if !strcmp(work 'flower') 

# if we're here, varnum is the first 

# GV_NAME that begins with " flower" , 

# and there is at least one such 

# variable. 



) 



endif 



hex2dec(va/) 



given a hexadecimal number, returns its decimal equivalent. 



index {pattern s [start]) 



returns the number of the byte where the pattern string occurs 
within the searched string s\ or returns -1 if pattern is not found 
in s. The value returned counts from the beginning of the string 
(where is the first byte), regardless of the (optional) start position 
start. 



int (val) 
isdir {path) 



returns the integer part of val If val is 24.5 L int (val) will 
be 24. 

returns 1 if path is an extant directory, C ;f L does not exist or 
it is not a directory. 
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isfile (pafA) 
is real (string) 
length (var) 

1 va r num ( varname ) 



max (varname varname) 
mi n ( varname varname ) 



returns 1 if path is an extant file, but not a directory. Otherwise 
returns 0. 

returns 1 if string is some real number (e.g.: 1, -12.3, .3314, 
etc.), or if it is not (e.g.: 23-44, 1.2.a, Fred). 

returns the length of the string contained in var, or -1 if there is 
no variable named "var." This function can be used to determine 
whether a variable exists. 

returns the element number of the LV__NAME [ ] (local variable 
name) and LV_CONT [ ] (local variable content) arrays which 
corresponds to varname, if it exists, or the element number where 
it would be if it were inserted alphabetically. You cannot tell 
whether varname exists by using lvarnumf); use 
length ( ) for that purpose. See also gvarnum ( ) for more 
information and an example. 

yields the larger (smaller) of the two values. 



nameemp (target pattern) compares two filename strings to see if they qualify as a match 

in the OS-9 world. The target string is an actual filename. Two 
metacharacters are recognized in the pattern string: ? matches 
any single character and * matches any string of characters. 
Upper/lower case distinctions are always ignored Returns if 
there is a match, or -1 if not. 



oct2dec(va/) 



rand ( ) 



strcmp(a b) 



given an octal number, returns its decimal equivalent. 

returns a 31 -bit pseudo-random positive integer. (See also the 
set rand and randlist commands.) To obtain a random 
integer with 11 different possible values in the range to 10, 
inclusive, use: 

rand() % 11 

returns a negative number if string a is lexicographically less than 
(i.e., prior to) string b; a positive number if b < a; or if the 
strings are identical. 
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System Variables 



System variables are used just like all other variables (see Sections 7 and 8). 



ERROR REPORTING 



e__banner 



is a pseudo-variable containing the time and date of this particular 
invocation of OJ, the invocation name of OJ itself, the invocation 
name of the current script, the current line number in that script, and 
the do stack of calling scripts, if any. For example: 

90/05/19 15:51:06 oj {intcept_handler ( ) } : 
OJ interrupted by signal 3. line 9 of 
script 
" /dd/USR/ SCRIPTS /massedit . oj " 
It is often good to use this in an fprintf (possibly to 
$stderr) just before exiting on account of some error condi- 
tion. 



qreturn 



is a local variable which contains an integer value returned by a 
number of OJ commands. Its value should always be checked im- 
mediately after any command which sets it, lest some succeeding 
command set it to another value before it is checked. You can use 
either switch or if to check qreturn, as neither switch 
nor if sets qreturn. The values of qreturn are interpret- 
able by system pseudp-variable e_msg [ $qreturn] . They are 
also listed in Section 13. Generally speaking, if all went well, 
qreturn >= 0; if not, qreturn is some meaningful negative 
value. 



E_NONINT, etc. 
(see Section 13) 



are error condition constants available as global variables, containing 
integer values. These should be treated as constants to compare with 
the value of qreturn to check for specific error conditions re- 
ported by qreturn. For a complete list of these, see Section 13. 
Instead of doing this: 

if (qreturn == -2) 
do this: 

if (qreturn == E_NONINT) 
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because the exact value of E_NONINT may change in future ver- 
sions of OJ, whereas the meaning of E_NONINT will not change. 



e_msg [$qreturn] is a pseudo-array of variables containing brief messages, one per array 
(see Section 13) element, explaining the meaning of the value of qreturn used as 

the index value. Each message also contains the CONSTANT name 
of the particular value of qreturn, e.g.: 



E_NONINT: an integer value was 

required; this wasn't one 



INPUT/OUTPUT 



stdout, stderr are output file handled for writefile and fprintf. Unless 
OJ*s own standard output and/or standard error stream has been re- 
directed elsewhere, both will go to the console screen. Both are 
global variables. 



MEMORY MANAGEMENT AND DATABASE-LIKE OPERATIONS 

(see also the system functions gvarnum() and lvarnum() in Section 8) 



LVARS 
GVARS 
LV_NAME[/i] 

GV_NAME[/i] 

LV_CONT[n] 

GV_CONT[/i] 



is the number of local variables currently in existence. 



is the number of global variables currently in existence. 

is a way of accessing the names of all the local variables. The index 
must be an integer in the range to (LVARS - 1). 

is a way of accessing the names of all the global variables. The 
index must be an integer in the range to (GVARS - 1). 

is a way of accessing the contents of all the local variables. The 
index must be an integer in the range to (LVARS - 1). 

is a way of accessing the contents of all the global variables. The 
index must be an integer in the range to (GVARS - 1). 
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MISCELLANEOUS 



argc 



argv[0...n] 



curscript 



exitstat 



systime 



systimef 
procid 



is a local variable containing the number of arguments (argc stands 
for "argument count") passed to the script, either at OJ invocation 
time or via a do command. The script name itself counts as one 
argument, so the value of argc is always at least L 

is the arguments passed to the current script. argv[0] is the name 
of the script (but only if it is the original or the including 
script— the name of any included script exists only in the vari- 
able curscript [see below]), argv's index value has a range 
of to (argc-1). (argv stands for "argument vector"; in com- 
puterese a "vector* 1 is usually a list of some kind). The array ele- 
ments of argvf ] are all local variables. 

gives the name of the current script, whether it is an including 
or an included script. 

is the exit status value of the most recent OS-9 command, or the 
value returned by a called (i.e. done) script to the calling (i.e. 
doing) script, exitstat is useful when you've used a hyphen 
before an OS-9 system call (an invocation of any regular OS-9 pro- 
gram) to prevent OJ from aborting on a non-zero exit status from 
that invocation. (See the anyjDS-9_programJnvocationjiame 
command at the beginning of Section 11.) For a discussion of the 
exit status of a done script, see the descriptions of do and re- 
turn, exitstat is a local variable. 

is a pseudo-variable containing the date and time current to the sec- 
ond, in the form yy'/mm/dd hhimmiss. The hour number is 
given in military (i.e. 24-hour) form. For example, March 8, 1989 
at 12:38:02 A.M. would appear as 89/03/08 00:38:02. The 
same day at 8:32:00 P.M. would appear as 89/03/08 
20:32:00. This is not really a variable a t all, but you use it 
just as if it were one. 

is the same as systime, but: without punctuation, for use in 
filenames. E.g.: 890308203200 

is a global variable containing the OJ interpreter's process ID in ex- 
actly five digits (with leading zeros, if needed). 
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P wd ^ a pseudo-variable containing the current working data directory, 

expressed as a full pathname beginning with an explicit device name. 

user id is a global variable containing the current user's group/owner id num- 

ber, in the form 255.254 if group is 255 and owner is 254. 



SOCKET INTERACTION 

reply [] (See send command description.) 

ereply[] (See send command description.) 

sendbuf [] (See send command description.) 
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Backslash-Interpreting Commands 



In "backslash-interpreting commands," backslashes indicate special (often non-printable) char- 
acters in strings; this usage is generally similar to that used in the C language. 

In the backslash-interpreting commands, token strings may contain any of the following special 
conversions to single byte values: 



String 



\r 



\n 



\1 



\f 



\t 



\b 



\\ 



\$ 



\# 



\d001 



\001 



\x01 



Byte value 



OdH 



OdH 



OaH 



OcH 



09H 



08H 



5CH C\V) 



22H CX") 



24H (*$•) 



23H ('#') 



01H 



01H 



OIH 



meaning 



carriage return 



another way to say carriage return 



linefeed 



formfeed 



tab 



backspace 



a backslash 



a double quotation mark (double quotation 

marks are otherwise assumed to surround 

tokens and will be discarded during 

tokenization) 



allows a token to begin with $ without 
forcing variable substitution 



allows a token to begin with # without 
initiating a comment 



decimal value of 1 



octal value of 1 



hexadecimal value of 1 



NOTE: as character substitutions in hard strings are done before variable substitutions no 
variable substitution will occur if the original token began with \$. This means that \$var 
will become $var but but will not undergo variable substitution. 



29 



Section 10: BACKSLASH-INTERPRETING COMMANDS 



NOTE: Use 3 digits for decimal and octal and 2 digits for hex, even if you don't need them. 
This prevents subsequent valid characters from being treated as part of the value of the byte. 

The backslash-interpreting commands include array tok, fprintf, send, set (note 
especially the =R option), set_mbf, sprintf, replace, and writer ile. The 
alphameric command performs backslash-deinterpretation. 
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Commands 



external process control any-QS-9 -program Jnvocation.Jiame 

format: (Just like any OS-9 shell command line, with a few differences. See the docu- 
mentation on the Microware "shell" program in the OS-9 user manual, and the 
notes below.) 

purpose: The tokens, after variable substitution, if any, will be concatenated into a string 
which will become a command line passed to the OS-9 "shell" program. Exe- 
cution of the script will halt until the program has finished running. Example: 

dir /hO > $fn 

will cause dir to be run on /hO, and the standard output to be written on 
the file whose name is stored in variable f n. 

notes: (1) Concatenation of tokens is not handled the same way as in all other OJ com- 
mands. The separate tokens are concatenated into a string with spaces between 
them, except that redirection operators are snugged up against the tokens they 
modify. 

(2) Redirection operators (< , > , ! , ») must be single tokens; they should be 
followed by whitespace, even though this is not normal OS-9 practice. This is 
to allow variable substitution to take place in the normal way. 

(3) If the exit status of the program is non-zero, OJ will abort immediately, unless 
the command is immediately preceded by a dash (-). For example: 

-del e will not abort the script even if e does not exist and therefore del 
returns non-zero status. Afterwards, the exit state may be found in the system 
variable exits tat. 

(4) Invocations of OJ itself are automatically altered in such a way as to cause certain 
OJ modes to propagate to the forked OJ process (see oj command). 

(5) This command sets qreturn; check for E„PSNOFORK, E_PSWENTAWAY 
values (see Section 13). 

(6) See also the redirect command. If a redirect is in effect, the OS-9 
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"shell" program does not mediate the invocation, and redirection operators may 
not be used. 

(7) For interactive control of a forked process, use socket instead. See 
socket, send, etc. 

(8) There must be a one-to-one correspondence between the arguments to the invoked 
program and the tokens used to create those arguments. For example, the fol- 
lowing example will not work, because instead of getting two arguments, "-d" 
and "-1", Is will get only one strange argument, *'-d -1": 

set argl = "-d -l w 
Is $argl 

On the other hand, this will work fine: 

set argl = n -d" 
set arg2 = "-1" 
Is $argl $arg2 

It is sometimes extremely inconvenient to make a one-to-one correspondence be- 
tween tokens and arguments. For that reason, a special format is provided for 
strings which contain multiple arguments, separated by whitespace, that you want 
to have parsed into separate arguments. The trick is this: begin such a single 
string with a # character. (This requires the use of a backslash when first setting 
a variable to it, so that it is not seen as a comment-begin delimiter.) For example, 
this will work: 

set argl = ■ \# -d -1" 
Is $argl 

The fact that the above method is supported by OJ makes it impossible to create 
a single argument string for an OS-9 invocation which both begins with a # and 
also contains spaces. It seems unlikely that anyone will need to do this very 
often, though. Note also that the pound sign in OS-9 is used to specify the stack 
space of the forked process. Since it will be stripped, use two of them: 

foo \#\#58 # 58 k of stack space. 
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string manipulation 



alphameric 



format: 
purpose: 

notes: 



alphameric var_to_set = string_l {...string_n) 

Mainly for making debug displays; replaces non-alphameric bytes, such as OdH, 
with backslash-preceded equivalents, such as \r. Uncommon byte values are 
given in hex, as, for example, \x00 for a null byte. 

alphameric reverses what happens to hard strings in backslash-interpreting 
commands (see Section 10). See also the set command in Section 11, which 
has approximately the opposite effect of alphameric (especially the =R op- 
tion of set). 
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arraytok 



string manipulation 



format: arraytok separator jcharacter(s) array name (option) 
string_l (...strings) 

(NOTE: as with all commands, this one must be written alJ on one line in the script. 
If it won't fit, use the backslash line-continuation feature [see Section 6].) 



option: 



-GOBBLE or -NOGOBBLE (default) 



purpose: Create an array of variables each containing a token from the line. 



notes: First, string_l . . . string_jx are concatenated. Then the single long string thus 

concatenated is re-divided into tokens wherever any separator character appears. 
All separator characters are discarded. Each token is then stored in an element 
of an array of variables whose name is array name [ ] . . . arrayname [ n ] . 
The variable arrayname, without an index, contains the number of valid ele- 
ments in the array. To cause the array to be created as local variables, precede 
arraytok with a 

local arrayname 

If no option is given, or if the default option -NOGOBBLE is (redundantly) 
specified, each appearance of the separator character will cause a token to be 
created, even if no other (i.e., non-separator) characters appear between them. 
This is useful in cases where a line of data is separated into fields by field 
separator characters, and it is necessary to render even empty fields into numbered 
tokens. 

Alternatively, if the -GOBBLE option is specified, wherever one separator char- 
acter immediately follows another (with nothing to tokenize in between) no empty 
token will be created. This is useful if, for example, it is necessary to divide a 
line of text into separate tokens, and discard all spaces and tabs between them. 



Here are three examples: 
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Example 1: 

set path = /hO/USR/SRN/TOOLBOX/OJ 
arraytok / pathitem $path 

fprintf $stdout "pathitem == %d\n" $pathitem 
loop 1 ; ctr = ; ctr < pathitem ; \ 

ctr = ctr +1 # rest of loop command 

fprintf $stdout \ 

w pathitem[%d] == %s\n" $ctr 
$pathitem[$ctr] 
1 

Output from code in example 1: 



pathitem == 
pathitem[0] 
pathitem[l] 
pathitem [2] 
pathitem[3] 
pathitem[4] 
pathitem[5] 


6 

== «h0" 
== "USR" 
== "SRN" 
== "TOOLBOX" 
== "OJ" 


Example 2: 





set a = "the quick" 
set b = "fox" 

arraytok " " f oo $a brown " " $b \ 
"jumps over the lazy dog." 

# there are 3 spaces between the 

# words "jumps? and "over" 
fprintf $stdout "fob == %s\n" $foo 

loop ; ctr = ; ctr < foo ; ctr = ctr + 1 
fprintf $stdout "foo[%d] == \"%s\"\n" $ctr \ 
$foo[$ctr] 


Output from code in example 2: 



35 



Section 11: COMMANDS 



foo == 


9 




foo[0] 


== 


"the" 


footH 


== 


"quickbrown 


foo[2J 


== 


"fox jumps" 


foo [3] 


== 


h n 


foo [4] 


== 


n it 


foo[5] 


== 


"over" 


foo[6J 


5= = 


"the" 


foo[7] 


s: = 


"lazy" 


foo [8] 


= == 


M dog . " 



Example 3: 



# just like Example 2 except -GOBBLE option is 

# added to arraytok, 2 tab characters are added 

# after "jumps", arid spaces and tab characters 

# are identified as separator characters: 
array tok " \t" foo -GOBBLE $a brown ■ " $b \ 

"jumps\t\t over the lazy dog." 



Output from code in example 3: 



foo == 


7 


foo [0] 


== "the" 


foo[l] 


== "quickbrown 


foo[2] 


== "fox jumps" 


foo [3] 


== "over" 


foo [4] 


== "-the" 


foo [5] 


== "lazy" 


foo[6] 


== "dog. " 



Note that the empty fields were "gobbled up"— i.e. they disappeared. 

As is obvious from the above Example 3, arraytok is a "backslash-interpre- 
ting" command. 
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string manipulation 5 j(§ 

format: bits var = decimaljnteger 

purpose: Store the string of thirty-two Vs and 0*s representing the condition of the bits 
of a 32-bit integer whose value is the decimal value given. 

notes: Four tokens. 
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" rea ^ flow of control 

format: break 

purpose: (1) Immediately cease iterating the nearest enclosing loop, and restart the program 
at the ending label of that loop. 

(2) Proceed immediately to the statement label at the end of the nearest enclosing 
switch, skipping all the rest of the cases, etc. 

notes: Exactly 1 token. Not a valid command unless there is a loop or switch 

in progress to break. 
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calculation calc 

format: calc resultvarname = calc_expression 
purpose: Make a calculation and store the result in resultvarname. 

notes: See Sections 7 and 8. Variables whose names appear in the expression will 

undergo substitution even without the use of the $ character. This can be pre- 
vented by using single quotation marks. 
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case flow of control 

format: case string_to_match_in__a_switch 

purpose: See switch. 

notes: Only valid within a switch region. 
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miscellaneous q(\ qJ|J 

format: c d directory _to_become_current_data_directory 
or 

chd directory Jo J>ecomej:urrent_jiata_d\rectory 
purpose: Change current data directory. 



notes: See the chd command (actually the chdir() function) in the OS-9 user manual, 

qreturn will be if the command was successful. There is no difference 
between cd and chd. 
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chx 



miscellaneous 



format: chx directory__tojbecome_current_execution_directory 
purpose: Change current execution directory. . 



notes: 



See the chx command (actually the chxdiro function) in the OS-9 user manual 
qreturn will be if the command was successful. 
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input/output 



closefile 



format: closefile file_handle 

purpose: Close a file which is already open, thus writing to disk any buffered data which 
hasn't been written there yet, and releasing the OS-9 path table slot associated 
with it. 



notes: 



Don't forget to use a $ before the file handle variable. Sets qreturn to 
E--NO_ERR (0) if all went well. 



See also openfile, readf ile, writef ile, fprintf, 
seekfile, and tellf ile. 
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continue 



flow of control 



format: continue 

purpose: Immediately start the next iteration of the nearest enclosing loop, without ex- 
ecuting the remainder of the current iteration. 



notes: 



Exactly 1 token. Not a valid command unless there is a loop in progress to 

continue. See loop. 
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debugging debug__on (debug_off) 

format: debug_on 



or 



debug-off 
purpose: Turn on (off) the debugger. 



notes: Inserting a debug_on in a script has the same effect as setting a debugger 

breakpoint on the following executable line. See Section 12. 
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default flow of control 

format: default 

purpose: See switch. 

notes: Only valid within a switch region. 
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time measurement 



difftime 



format: difftime target_varname = marktime _value_„l 
marktime __value_2 

(NOTE: as with all commands, this one must be written all on one line in the script. 
If it won't fit, use the backslash line-continuation feature [see Section 6].) 

purpose: Write on the target _yarname the number of seconds, including any fraction of 
a second, between the time when marktime _yalue_l was set by marktime 
and the time when marktime _yaluejl was set by marktime. 

notes: In general, if predictability and/or accuracy are critical, try to avoid disk input/out- 

put between one marktime and another. With care, accuracy levels in the 
neighborhood of 0.1 second should be attainable. There are several possible uses 
for this command, including experiments intended to show which of several OJ 
programming algorithms is fastest. When performing such experiments, it is im- 
portant that the system is otherwise idle, and that the code be iterated many 
times. Note that marktime and difftime can not be used to measure 
processing time, only elapsed real time. 

For example: 



marktime timeO # start timing now 

# something happens here and you want to 

# know how long it takes. 

marktime timel # make a note of the time here. 

difftime elapsed = $timeO $timel 

fprintf $stdout "It took %.2f seconds to do it.\n" 



\ 



$elapsed 



See also irarktime and julia" 
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do 



flow of control 



format: do OJ ^script jname (arg_l ...arg_n) 



purpose: Execute the named script as a subroutine. 



notes: 



The arguments passed to the subroutine, if any, will appear as argv [1 . . .n] ; 
the subroutine's name will appear as argv[0] . 

The subroutine script will share all the global variables already in existence with 
the calling script, and any global variables it creates will still be around when 
the subroutine returns. It will, however, have its own independent bank of local 
variables, including the system Variables argc, argv[0. . .n], ex- 
itstat , and qreturn. See the local command. 

The called script and the calling script will not know about each other's statement 
labels or loops; i.e., you may not have a goto, switch, or loop in one 
script which refers to a label in another script. 

The called script's return value is available to the calling script as ex- 
itstat (see the return command). 

The degree to which you can nest do commands is limited by the size of the 
OS-9 file stream table, which usually can have 32 entries. All open files use up 
one entry each. This means that if you write a script that calls itself recursively 
via do, it can recur at most 31 times before a "path table full" error aborts OJ 
altogether. 
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debugging 

format: echo_on 
or 



-non jlI: <^.>imvlAr< OS 



echo_on (echo_off) 



echo_of f 



purpose: The single most useful script debugging command. Causes OJ to output each 
command line to be executed (does not show unexecuted command lines) after 
variable substitution, but before execution. (Echo output is made to the console 
via stderr.) 

notes: Exactly 1 token. The first item on each output line is a letter; A means the 

invocation script, B the script called by the A script, C the script called by the 
B script, etc. After this letter comes the line number, followed by the line itself. 

The functionality of echo_on and echo_of f are available in the interactive 
debugger via the el and eO commands (see Section 12). 
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else 



flow of control 

format: else 

purpose: (See if command) 



notes: Exactly 1 token. If you don't need an else, you don't have to use one. Re- 

quires prior use of an if. 
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flow of control endif 

format: endif 

purpose: (See if command.) 

notes: Exactly 1 token. Requires prior use of an if. 
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eXlt flow of control 

format: exit { calc_expre$sion ) 

purpose: Terminate OJ altogetf and, optionally, set the exit value of the OJ interpreter. 



notes; 1 or 2 tokens, if used, the optional second token must evaluate to an integer 

If there is no second token, OJ's exit status will be 0. See Section 8. 
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input/output 



fprintf 



format: 
purpose: 

notes: 



fprintf filejxandle control^string {string_l ...string_n) 

Write a formatted string on a file (or $stdout or $stderr) using the same 
control string and conversion conventions as the fprintfo function in the C lan- 
guage. 

Please refer to Kemighan and Ritchie's The C Pro gramming Languag e or any 
other good book on C. To output text to the screen, use 

fprintf $stdout . . . 



or 

fprintf is a "backslash-interpreting" command. 

See also openf ile, closef ile, readfile, writef ile, 
seekfile, and tellf ile. See also sprintf. 
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goto 



flow of control 



format: goto label 



purpose: Resume execution elsewhere in the script. 



notes: 



If at all possible, this command should be avoided. It has the effect of cancelling 
all switches and loops which may be in progress. Its only proper function 
is to allow there to be only one place within a script to be jumped to prior to 
an on-error exit or return, so that error reporting code need not be dupli- 
cated all over the place. See the label command. 
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flow of control 



if 



format: i f calculational^expression 
purpose: Conditionally control script execution. 



notes: 



Used with else and endif in the usual fashion. If the expression is eval- 
uated as non-zero, it will be regarded as true. 

2 or more tokens. Requires the use of endif to define its region of effect. 
The use of else is optional. 

For example: 

if (calc expression evaluating non-zero) 

# commands in this region 

# will be executed 
else 

# commands in this region 

# will not be executed 
endif 

See also Section 8. 
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ignore 



socket interaction 



format: ignore socket ^handle 



purpose: Discard all bytes received from the socketed device or process during tht 
next send. 



notes: 



ignore is generally used only when the number of bytes is expected to be 
very large and occupy too much memory uselessly. 

ignore affects only the very next send to the specified socket Jiandle, 
One effect of ignore is that all of the waits specified by any preceding 
set-waits will be fully satisfied before the send is completed. 

See also send, set-waits. 
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flow of control 



include 



format: 
purpose: 



notes: 



include oj_$cript_name 

Exactly the same as do, except that an included script has the same local 
variables as the including script. In other words, the scope of the including 
script's local variables is increased to encompass the included script, and so in 
a way, those local variables are globalized. This is useful for passing argc 
and argv[0 . . .n] through to a called script, for example. 

Always exactly 2 tokens. No arguments can be passed. The command is called 
"include" because it is as though the included script's code is inserted whole- 
sale into the including script's code. However, as in do, the including 
script's exit stat can be set by using the return command in the in- 
cluded script. 
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istop (istart) 



flow of control 



format: i s t op 

or 

istart 



purpose: 



notes: 



Turns off (on) the interpreter unconditionally for any number of lines. Allows 
documentation to appear within a script without the necessity of beginning each 
line with a comment character (#). 

Once an is top has been encountered, the only way to restart interpretation is 
with an istart. If the interpreter is already enabled, istart has no effect 
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time measurement 



Julian 



format: Julian varJorJiay_number var_for_second_number 
varjorjick^number varJor_ticks-per-second_value 
= marktime_value 

(NOTE: as with all commands, this one must be written all on one line in the script. 
If it won't fit, use the backslash line-continuation feature [see Section 6].) 



purpose: 



Display exact date and time (to the clock tick) when a mark time was exe- 
cuted, in Julian format. 



notes: 



The day number will be a Julian day number. The following information, quoted 
from We bster's Third New International Dictionary , i s relevant: 

"A Julian period is a chronological period of 7980 Julian years that com 
bines the solar and lunar cycles and the Roman indiction cycle and is 
reckoned from the year 4713 B. C. when the first years of these cycles 
coincided. 

"A Julian year is exactly 365 days, 6 hours, adopted in the Julian cal- 
endar. 

"A Julian day number is the number of a day in the Julian day calendar 
(as 2,436,934 for January 1, I960)." 

The second number will be the number of the second since midnight. There are 
86,400 seconds in a day. 

The tick number will be the number of ticks since the beginning of the second. 
The ticks-per-second value is just what it says it h. This value is provided be- 
cause different OS-9 systems may have dJf^rent numbers of ticks per second. 
See marktirne and dif f time; see th- systime ?nd systimef sys- 
tem variables if Julian dates are nc : what yn *v?jit. 

For example: 

mark time timenow 

Julian day sec tick tps = $ timenow 

fprintf $stdout \ 

"day is %s; sec is %s; tick is %s; %s 
ticks/sec\n" \ 

$day $sec $tick $tps 
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label 



flow of control 



format: label 

purpose: Mark a position in the program at which a goto command can restart execution, 
. or at which a loop or switch region ends. 

notes: Labels must begin with a decimal digit (0-9), and thereafter they (like variable 

names) must consist entirely of alphabet characters (both upper and lower case), 
numeric characters (0 through 9), periods (.), and underscores (_). No two 
labels can be the same in any one script. A valid label can have only one token 
on the line. A label can be any length. 
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memory management 



local 



format: local varname^l (...varname_n) 

purpose: Force all the varnames to be local variables henceforth within this script (but 
not within any done or doing scripts). 

notes: There are two classes of variables in OJ. One is called "global," and the other 

is called "local.*' Both kinds work the same way, and they are used in the same 
ways. Indeed, you can ignore the distinction entirely, in which case all your 
variables will be global, except for the system variables qreturn, ex- 
itstat, argc, and argv[0 . . .n] , which are always local regardless of 
anything you may do. 

Global variables are created automatically whenever you set them for the first 
time. They are available thereafter throughout the entire invocation of OJ, in all 
called and calling scripts. Similarly, any global variables created and/or set in 
any scripts called via the do command will continue to exist and retain their 
new values even after the done script has returned to the doing script. 

Local variables are created by the local command. Any script which uses 
local variables should declare them at the beginning of the script with one or 
more local commands; this practice will make the script easier to maintain. 
However, it is ok to use local before any other mention of the variable, even 
if the local does not appear at the beginning of the script. 

Whenever a variable is mentioned by name, OJ looks to see whether it exists. 
It always looks first in the banktof local variables, and if it is not there, it looks 
in the bank of global variables. If the variable does not exist and must be set 
to some value, the variable is created as a global variable. 

The only way to create a local variable is to use local. The effect of a 
local is to create the named variable(s) in the bank of local variables, with 
no content (i.e., with null strings) in them. Thereafter, OJ will find them there 
first and not even bother to look in the bank of global variables for them. 

When a called script terminates (encounters a return or comes to an end), 
its local variables go away, never to be seen again. It is extremely useful to 
have variables that are "local" to a script so that it can call itself recursively 
without the various recursions overwriting each other's data, and so that the mem- 
ory allocked to its local variables can be recovered automatically at its end. 
When a s.'ipt with local variables calls another script with local variables, even 



61 



Section 11: COMMANDS 



if those local variables have the same names, there will be no interference be- 
tween the two scripts. In general, it is advisable to use local variables, and write 
your scripts as modules that can call one another via do. Since the local vari- 
able bank is always consulted first, your scripts will run faster. 

Here is a demonstration of the use of local variables: 

# demo.oj begins here 

fprintf $stdout "Type a string > ■ 

stdin astring # user types a string here 

do capitalize $astring bstring 

# call capitalize. oj 
if exitstat 

exit $exitstat # an error occurred in 

. # capitalize. oj 
endif ' 

fprintf $stdout \ 

"The capitalized string is: \"%s\"\n" $bstring 
fprintf $stdout \ 

"The original string was: \"%s\"\n" $astring 

# demo.oj ends here 

# capitalize. oj begins here 

local astring # this will not be confused with 

# the global astring, if there 

# is one (which there is) . 
if (argc != 3) 

fprintf $stuen \ 

"\"%s\" requires 3 args; you provided %d. B \ 
$argc 
return 1 # a general on-error value 

endif 

set astring = "X" # "astring" in "demo.oj" will 
# not be overwritten by doing this, 
set $argv[2] =U $argv[l] # capitalize first arg 

# and set the global var 

# in the second arg. 
return # this is not really needed 

# since this is the end. 

# capitalize. oj ends here. 

See also vsave, vrestore. 
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flow of control 



loop 



format: loop endjabel ; (init_yar = 
initialization_calc_expression ) ; 

{test_calc_expression) ; (increm^var = 
incrementing__calc_expression) 

(NOTE: as with all commands, this one must be written all on one line in the script. 
If it won't fit, use the backslash line-continuation feature [see Section 6].) 

purpose: Keep looping (i.e., repeatedly execute the code between the loop command line 
and its ending label) until the test_expression evaluates to 0, or a break 
command is encountered. 



notes: 



Everything is optional except the three semicolons and the endjabel The semi- 
colons must always be present, and they must be surrounded by whitespace (i.e., 
be separate tokens). See also break, continue, and label A loop is 
executed in the same way that "for" loops are executed in the C language: first 
the initialization_calc_expression is evaluated and the result is stored in 
init_var. Then the test_calc_expression is evaluated. If the test_calc__ex- 
pression evaluates as 0, the program recommences at the loop's endjabel and 
the loop's contents, i.e., the OJ command lines which lie between the loop 
command and the line on which its endjabel appears, are not executed. If the 
test _calc ^expression evaluates non-zero, the contents of the loop are executed. 
When the endjabel is encountered, the incrementingjcalcjexpression is 
evaluated and the result is stored in incremjvar. Then the test_calc_expres- 
sion is re-evaluated. If the test_calc__expression evaluates 0, the loop is 
terminated. In other words, the^ode within the loop will be executed itera- 
tively only as long as the test_salc_expression evaluates non-zero. See Sec- 
tion 8. 



Usually, of course, init^yar and incremjvar will be one and the same variable. 
Following is an example of a typical loop which will be iterated ten times; 
on the first time through the loop, the variable loopvar will have a value 
of 0, and on the last iteration loopvar will have a value of 9. 

# a plain vanilla loop 

loop 0432this_is._the_end_label ; loopvar = ; \ 
loopvar < 10 ; loopvar = loopvar + 1 
fprintf $stdout "loopvar == %dAn" $loopvar 

0432t;his_is_the_end_label 
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marktime 



time measurement 



format: marktime varname 



purpose; Record the current date and time, accurate to one OS-9 clock tick (often 1/128 
of a second). 



notes: 



This command is used with dif f time to measure an interval of elapsed time. 
This is useful for optimization of procedures, for checking system loading, etc. 



See dif f time and Julian. The string stored in the variable is interpret- 
able only by dif f time and Julian. There is no point in displaying it; 
it is not a character string. 
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flow of control 



OJ 



format: 



oj oj^script_name (arg__l...arg_n) 



purpose: Re-invokes OJ as a subprocess, automatically propagating operating modes as 
shown in the following table: 



if this mode is in effect: 


then the argument automatically ap- 
pended will be: 


--d (debug mode) 


- -d (unless backgrounded with &) 


--eor echo_on 


- - e (unless backgrounded with &) 


echo_off 


none 


- -v or verbose_on 


- - v (unless backgrounded with &) 


verbose— of f 


none 


--x or 

sys_exec_of f 


--x 


sys_ exec_on 


none 


- - q (quiet mode) 


--Q 



(For information about OJ invocation parameters [such as -q], see Section 4). 

notes: This command is generally not what you want unless you want to fork OJ as a 

background process. See the do command, which has far less overhead and 
which allows the sharing of global variables between the calling and the called 
script. 

This is actually handled just like any other OS-9 process invocation (see 
any_OS-9j)rogram_invocationjname at the beginning of this Section), ex- 
cept for the forced inheritance of the operating parameters described above. The 
current OJ process's variables and the subroutine's variables are totally separate 
and independent of each other. This command sets qreturn; you might want 
to check it for equality to the E-PSNOFORK and E-PSWENTAWAY error values. 
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openfile 



input/output 



format: openfile varjorjilejxandle = file_name action 
purpose: Open a disk file for reading, writing, etc. 



notes: 



If the file could not be opened for some reason, the varjorjxlejxandle will 
be set to '0* and qreturn will be nonzero. If all went well, qreturn 
will be E_NO_ERR (0). All other file i/o commands require the file handle 
value placed in varjorjilejxandle by openfile. actions are as fol- 
lows: 

r open for reading. /Useful for checking to see whether a file exists. 



w 



r+ 



w+ 



a+ 



open for writing. Cuirent contents are lost. Creates a file if nec- 
essary. 

append (write) at end of file, creating a file if necessary. 

read from and write to the file. Nondestructive of existing con- 
tents until you overwrite them with awritefile command. 

read from and write to the file. If the file exists, its contents are 
destroyed; if it does not exist, it is created. 

read anywhere in the file, but only write at the end of it. 



For output to stdout or stderr, no openfile is necessary. $stdout and 
$stderr are the file handles for the standard output and standard error 
streams. 

See also readfile, writef ile, closefile, fprintf, seekf- 
ile, and tellfile. 



66 



Section 11; lOMMAN^ 



socket interaction 



password 



format 1: password 



format 2: password = string 



purpose: Set the password string. This string is useful only in a send (see send). 



notes: If the first format is used, the user is interactively asked to type in the password. 

The password will not be displayed or echoed to the screen. The user will be 
asked to type the password twice at pairs of prompts until the two strings match. 
If the second format is used, the password is string. The token $ PASSWORD 
in any subsequent send will be replaced by this string. The password string 
is not a true variable: it cannot be used in any command other than send. 
Passwords are therefore secure except from users who can dump memory, or tap 
into the stream emerging from some serial device, or who can subvert a sock- 
eted process in some way. 
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randlist 



random numbers 



format: 



options: 



randlist arrayname arraysize lowest_possible_yalue 
number _of_possible_yalues ( option ) 

(NOTE: as with all commands, this one must be written all on one line in the script. 
If it won't fit, use the backslash line-continuation feature [see Section 6].) 

UNIQUE No two array elements may contain the same value. 

REPEATABLE The same value may appear any number of times within an array. 



purpose: 



notes: 



Create an array of variables whose name is arrayname, with a number of ele- 
ments equal to arraysize, and place in each one a pseudo-random integer whose 
least possible value is lowest_possible_value (which may be a negative in- 
teger) and whose greatest possible value is ([lowest_possibte_value + num- 
ber _of_possible_yalues\ - 1). 

If a UNIQUE is in effect, and number_of_possible_yalues is less than 
arraysize, OJ will abort. See also the rand ( ) function in Section 8 and the 
set rand command. If arrayname is a local variable, randlist will cre- 
ate the entire array as local variables. Otherwise, globals will be created. 
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input/output 



readflle 



format: readfile filejxandle var^for_line^fromJ r ile 

purpose: Place a newline-terminated line from the file into a variable. The newline will 
not be present at the end. 

notes: qreturn will be less than if an error occurred or if there are no more data 

in the file (in which case the qreturn value will be E_ RFEOF). Otherwise, 
qreturn will be a positive value equal to the number of bytes read. 

Don't forget the $ before the file handle variable. Don't attempt to read files 
which are not organized as lines of text. The readfile will continue until 
a newline byte is encountered, which may never happen. In such a case, the 
variable given as the third token may become quite enormous and use up all 
available memory, or simply abort OJ altogether with an "insufficient memory" 
error. 

See also openfile, closef ile, writefile, fprintf, seekf- 
ile, and tellf ile. 
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redirect 



externa! process control 



format: redirect stdin varname 

purpose: The standard input stream to the next OS-9 program invoked by the script will 
be the contents of the variable varname. varname should exist and should 
have something in it. 



format: 
purpose: 



format: 
purpose: 

notes: 



redirect stdout varname 



The standard output stream from the next OS-9 program invoked by the script 
will be to the variable named varname. When such an invocation takes place, 
the variable will first be initialized to a null string. This means that the contents 
of the variable will always be only the output of the OS-9 program. 

redirect stderr varname 

This is just like redirect stdout varname, except, obviously, it redirects 
stderr instead of stdout. 

Don't use a dollar sign before stdout or stderr; here they are keywords, not file 
handles. Normally, one probably would not want to use a $ with varname 
either unless the name of the variable to be used is the content of varname. 

If an OS-9 program invocation is not preceded by a redirect, OJ simply 
passes the whole string which comprises the invocation to the OS-9 "shell" pro- 
gram, which parses the string just as if it were typed at an OS-9 prompt, and 
then the shell program actually performs the invocation. However, after a re- 
direct somestream somevar, the subsequent OS-9 program call is not me- 
diated by the shell program. Therefore, if a redirect is in effect, redirection 
operators ( < , > , ! , » ) may not be used. See also any _OS -9 pro- 
gram Jnvocationjname at the beginning of Section 11. 
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string manipulation 



replace 



format: 



purpose: 



replace code:_S_or_C char(s)_jo_replace 

what_to_replace_them_with output_yar - string_l 
(...string_n) 

(NOTE: as with all commands, this one must be written all on one line in the script. 
If it won't fit, use the backslash line-continuation feature [see Section 6].) 

Replaces characters or strings within strings. First, replace concatenates 
stringy! . . . string jn into a single string, and then: 



If code is C: 



If code is S: 



All instances of each of the char(s)Jojreplace in the concat- 
enated string are replaced by the string whatJo_je- 
placejhemjwith. 

All instances of the entire string char(s)Jo_replace in the con- 
catenated string are replaced by the string whatJo_re- 
place_jhem_with. 



Then the resulting string becomes the content of outputjvar. 
notes: Must be at least 7 tokens. This is a "backslash-interpreting" command. 

Examples: 

replace S yellow green \ 

var = "I like the yellow ones." 

# $var now contains string: 

# "I like the green ones." 
replace C " e" "X M \ 

var = "I like the yellow cr.es. " 

# $var now con :^ ins string: 

# "IXlikXXt-XX; ~llov/XonXs> 
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return 

flow of control 

format: return (calculationaLexpression) 

purpose: (1) Terminate the cuirent script, arid return to the calling script at the next line below 
the do or include command which called the current script. 

(2) Optionally set the calling script's local variable exit Stat to the value re- 
sulting from evaluation of the calculationaLexpression. 

notes: If no argument is given, the calling script's exits tat will be set to zero. A 

return executed from a script which was not called via do (i.e., was invoked 
directly as an invocation argumenf to OJ itself) will behave like exit, and the 
OJ process will have the exit status resulting from the evaluation of the optional 
expression. 

The calculationaLexpression should always yield an integer value. 
For information on calculational expressions, see Section 8. 
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input/output 



seekfile 



format: seekfile fxlejxandle offset place 

purpose: Position the file pointer to a location within (or at the end) of an open file. 
offset is the number of bytes before or after place. If you wish to offset before 
place, use a negative number for offset. The values of place are as follows: 

beginning of file 

1 current position 

2 end of file 



notes: 



Don't forget the $ before ihtfilejiandle variable, qreturn will be set to 
E_NO— ERR ( ) if the seek is reasonable, or < if it couldn't be done for 
some reason. 

See also openf ile t closefile, readfile, writef ile, 
fprintf, and tellfile. 
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send 



socket interaction 



format: send socket Jxandle = 

var_to_receive_name_of„matched_buffer string_l 

(...strings) 

(NOTE: as with all commands, this one must be written all on one line in the script. 
If it won't fit, use the backslash line-continuation feature [see Section 6].) 

purpose: Send a string to a socketed process or device, await its reply, store its reply, 
and compare the reply to all associated match buffers. 



notes: This command is central to socket interactions. The strings are concatenated and 

sent to the pseudo-socket (the device or process) specified in a preceding 
socket, which returned the socketjtandle value. If the send was pre- 
ceded at some point by a 

socket sockhandle = /tl 

and then the send is executed: 

send $sockhandle matched "my string" 
The concatenated string sent to the socket is available, after the send, as 

$sendbuf [$sockhandle] 

A device's reply is stored in system variable $reply [$sockhandle] . In 
the case of a process-type socket, the process's stdout output is in 
$reply [$sockhandle] , and its stderr output is in $ere- 
ply t $ sockhandle] . If any of the match buffers set via one or more 
set— mbf commands are matched, the name of the buffer matched is written 
on v a r_to_receive_name_jof ^matched ^buffer. If no match buffer is 
matched, or if no match buffers were set prior to the send, or if an ignore 
command is executed prior to the send, the variable named in the second token 
will contain nothing (a null string). A special string in the concatenated string 
to be sent, $ PASSWORD, will be replaced by the string obtained by employing 
the (optionally interactive) password command. 

You must specify a device or process on which to perform i/o operations prior 
to the first send, by using a socket. 

This command sets qreturn; check for equality to E. NOSOCKET, 
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E_PSJUSTDIED and E-PSWENTAWAY. send is a "backslash-interpre- 
ting" command. 

See also ignore, password, set_mbf, set_send_.de lay, 
set-waits, show_mbfs, socket, strip_msb_on (_of f ) , and 
verbose_on (-off) . 
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set 



string manipulation 



format: set remltvc- = [option) strlng_l {...strings) 
options; =U 

=L 



All lowsrcase characters in the entire string will be converted to 

uppercase. 



All uppercase characters will be converted to lowercase. 



=R 



The content of all variables will undergo backslash interpretation 
(see Section 10) as well as all hard strings. 

No option used; , no conversions will be made. 



purpose: Concatenate strings into a single variable (resultvar). 



notes: 



May have 4 or more tokens, set is a "backslash-interpreting" command (see 
Section 10 and the alphameric command, which has the opposite effect). 
To set a variable to a null string, use 



set var = ■ " 
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socket interaction 



set mbf 



format 1; (For use if type_of_matchjO_make is BEGIN, END, or EXACT:) 

set_mbf socketjxandle name_of__bufferjo_set 
typej)fjnatchJojnake = stringy! {.. string ji) 

(NOTE: as with all commands, this one must be written all on one line in the script. 
If it won't fit, use the backslash line-continuation feature [see Section 6].) 

format 2: (For use if type _of snatch Jo _make is B&E:) 

set-mbf socketjxandle name_of_bujferJo_$et 
B&E separator = string J. („.string_ji) 
separator string jj {... string j?) 

purpose: Set a match buffer to the string concatenated from the tokens following the = 
sign (except separator). 



notes: 



OJ will strive to match all the match buffers that are set during the following 
send. The possible values of type_of_matchjo_jtiake are: 



BEGIN 



END 



EXACT 



B&E 
("Begin 
and End! 



Not very useful; the match will be made if the socket's reply 
begins with the string. All the waits required by the previous 
set_waits will occur. 

The match will bp made if the socket's reply ends with the string. 
As soon as the match is made, the send is over; the waits will 
not occur, so the time required to run the script is minimized. 

Like END but the match pattern and the socket's reply must ex- 
actly match if the match is to be made. 

The strings before tot separator will be concatenated and placed 
in the match buffer gfven r the name_of_bufferjo_$et token. 
The strings after the separator will he come* ! era fed and placed 
in a separate buffer. The oockefs reply will be matched if both 
the beginning and the end of it n>atch f>. £w corresponding buff- 
ers. 



Affects only the very next send encountered; send resets all match buffers. 
A "match buffer" is really just an ordinary variable with a special connection to 
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the next send; the special connection is destroyed by the send, but the vari- 
able is not destroyed. 

In the case of a process-type socket, all the match buffers will be compared with 
both reply [socket Jiandle] and ereply [socketjtandle] (i.e. stdoy* 
and stderr). 

set-mbf is a "backslash-interpreting" command. 



^eciioa ii; CUiViMANDS 



external process control 



set_prior 



format: set-prior calc_expression_yielding_j>rocess_priorityjvalue 

purpose: Set the processing priority of the OJ interpreter (and the default priority of all 
the processes it will fork later). 



notes: 



Beware setting priority so low it never gets executed, or so high it stops all other 
processes. See the OS-9 manual regarding the setpr utility for more information. 
See also Section 8 of this manual. 
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setrand 



random numbers 



format; 



setrand seed^string 



purpose: Set the seed from which all future random numbers (generated during the current 
invocation of the interpreter) will be generated, at least until the next setrand. 

notes: This command affects the randlist command and the rand() function. 

There is generally no reason to use this command except during debugging. 
When debugging, it is sometimes useful to set the seed so that the random num- 
bers generated will always be thp same. If there has been no setrand, the 
first time a rand ( ) or a randlist is executed, the seed is set automatically 
to a value based on the current date and time. If you do not use setrand, 
and instead rely on the automatic seeding feature, it should not be possible to 
get the same automatic seed twice within the same 500,000-day period. A com- 
forting thoughtl 

The seed_string must be exactly four bytes long. It cannot consist entirely of 
bytes (i.e., ■ \x00\x0 0\x0 0\x0 "), however. 
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socket interaction 



set_send_delay 



format: 



set-s end_del ay socket ^handle integer _value 



purpose: Set Ihe number of 256ths of a second to pause after sending each byte to the 
socketed device or process. 



notes: 



The default setting is 0. Typically you shouldn't need to use this command at 
all, but it is provided in order to accommodate certain devices that can't accept 
bytes at full speed. 

Exactly 3 tokens, send does not reset this parameter. See also send. 
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set waits 



socket interaction 



format: set -waits socket Jxandle integer _value 

purpose: For all succeeding send commands, set the number of half-second wait intervals 
to await more output from the socketed device or process, after the last byte 
is received. 

notes: Think of this as a "maximum pause with no response from the socketed 

device or process." If the output from the socketed device or process is 
matched by an EXACT, END, or B&E match buffer, these waits will not take 
place. If there is no match, or no match buffers have been set via one or more 
set— mbf commands, or an ignore command is in effect, these waits will 
all take place unconditionally. If no set—waits has been executed, the num- 
ber of waits will be 10 (i.e. 5 seconds). 

send does not reset this parameter. 

See also send, socket, set-mbf, ignore, and verbose— on. 
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debugging 



show_comIines_on (show_comIines_off) 



format: show-c oml ines-on 



or 



show—coml ine s_o f f 



purpose: For debugging. Causes OJ to output the command lines to the console (via 
stderr) as they are encountered, before they undergo any processing. Also shows 
whether the interpreter is currently searching for a particular label, and the current 
nesting level of if. 

notes: Exactly 1 token. This is probably not the command you want. You probably 

want echo— on and/or verbose_on, or you want to use the debugger. See 
echo_on, verbose— on, and Section 12. 
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showjabels 



debugging 



format: 



show—labels 



purpose: 



notes: 



For debugging. Causes OJ to output all known statement labels, and their line 
and byte numbers within the current script, to the console via stdeir. 

Exactly 1 token. Statement labels that have not yet been encountered will not 
appear in the list. This command is probably not what you are looking for, 
unless you are doing tricky stuff which uses the content of variables as labels. ' 
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socket interaction/ debugging show lllbfs 

format: show_mbfs socket Jiandle 

purpose: For debugging. Displays the currently active match buffers on the console (via 
stderr). 

notes: Remember that after a send all match buffers are cancelled. Therefore this 

command is useful only after one or more set_mbf commands, but before 
their associated send. See also send and set-_mbf. 
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show_tokens_on (show_tokens_off) 



debugging 



format: show—tokens—on 



or 



show_tokens_of f 



purpose: For debugging. Causes OJ to output all tokens to the console via stderr imme- 
diately after tokenization and before variable substitution. 



notes: 



Exactly 1 token. Makes an extremely verbose display. This command is prob- 
ably not what you want, unless you are wondering how a command line is being 
tokenized. See echo— on. 
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debugging 



show vars 



format: show-vars 



purpose: For debugging. Causes OJ to output the names and contents of all extant vari- 
ables to the console via stderr. 

notes: Exactly 1 token. It's usually easier to use the p command in the interactive 

debugger (see Section 12), but show.vars gives you a quick and dirty way 
to display the entire variable inventory on the screen. 
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socket 



socket interaction 



format 1: socket varJor_socketJ\andle = device^name 

format 2: socket varjor^ocketjiandle = pipe^sizejnjbytes 
process _name (process^arg_l... process_arg_n ) 

(NOTE: as with all commands, this one must be written all on one line in the script. 
If it won't fit, use the backslash line-continuation feature [see Section 6].) 

format 3: socket socket Jxandle 



purpose: 



notes: 



Specifies the device (format 1) ok invokes the process (format 2) with which to 
exchange data via the send command, or kills a process invoked by a previous 
socket (format 3). Formats 1 and 2 are used to set a variable to a socket 
handle value, which is required by all other socket interaction commands. 

Any number of socketed processes and devices can be kept on hand simul- 
taneously; each is independently addressable via its associated socket handle, via 
the send command. (See send.) 

You must execute this command prior to using send. Typically, for interactions 
with a host computer system, you will use format 1 and specify /tl or another 
serial port device. For interactions with some local process, such as Kermit, 
simply specify the variable name to receive the socket handle, the pipe size in 
bytes (minimum size is 256 bytes), and kermit: 

socket varjor socket Jmndle = 256 kermit 

In the case of a process, the process is invoked at the socket and it remains 
active until killed by a socket (format 3), or until it dies spontaneously, or 
OJ terminates. This command sets qreturn; be on the lookout for 
E-PSNOFORK and E-PSWENTAWAY values. 
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string manipulation 



sort 



format: sort source _array sorted_array (reverse) 

purpose: Determine the lexicographical (or reverse lexicographical) order of the items in 
an array. To get reverse order, use the optional final token, reverse. 



notes: 



source_array must be the source array name, which is a variable that must 
exist and must have as its value the number of elements in source jxrray [ ] . 
sorted^array is the name of the receiving array. This variable will be created, 
if necessary, as will all the elements of sorted^array [ ] . N.B.: to force the 
creation of the array as local variables, precede the sort with a 

local sorted_array 

The value contained in source_array will be copied into sortedjirray. The 
content of each element of sorted_array [ ] will be the index number of the 
corresponding element in source_array [ ] , not the value of the corresponding 
element in source_array [ ] . For example: (first we have to have have an array 
to sort) 



set sourcearray [0] = my 
set sourcearray [1] = dog 
set sourcearray [2] = has 
set sourcearray [3] = 
set sourcearray = 4 



Then we sort it: 



fleas 

# length of the array 



sort sourcearray targarray 

sourcearray is not affected. 

targarray has now been created, and it looks like this: 

$ targarray is "4"; 

$ targarray [0] is "1"; so 

$sourcearray [$targarray [0] ] is "dog" 
$ targarray [1] is "3"; so 

$sourcearray[$ targarray [1] ] is "fleas" 
$ targarray [2] is "2"; so 

$sourcearray [$targarray [2] ] is "has" 
$ targarray [3] is "0"; so 

$ sourcearray [$ targarray [3] ] is "my" 
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To display the items in sourcearray in alphabetical order, then: 

loop Oend ; i = ; i < $targarray; \ 

i = i + 1 

writefile $stdout $i ■ - $sourcearray [$i] \ 

n " $targarray[$i] \ 

" " $sourcearray[$targarray[$i]] \n 
Oend 

The above loop's output is: 

my 1 dog 

1 dog 3 fleas 

2 has 2 has 

3 fleas my 

If the sort command had been: 

sort sourcearray targarray reverse # reverse 
The output would have been: 

my my 

1 dog 2 has 

2 has 3 fleas 

3 fleas 1 dog 
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user interaction Spilldev 

format: spilldev device jname 

purpose: Pick up all bytes waiting at the named SCF device, and discard them. 

notes: Useful for clearing the standard input stream after displaying a dangerous prompt. 

fprintf $stdout \ 

"Press RETURN to launch nuclear weapons. \n" 
spilldev /term # no hangover RETURN key allowed to 

# start war. 
stdin x 

# launch nuclear weapons here. 
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sprintf 



string manipulation 



format: 



purpose: 



notes: 



sprintf varjto_he_set 
(string__l...string_n) 



control ^string 



Write a formatted string on a variable using the same control string and conver- 
sion conventions as the sprintf() function in the C language. 

Please refer to Kernighan and Ritchie's The C Prim ming f j,-, ,,^. or any 
other good book on C. sprintf is a "backslash-interpreting" command. See 
also f print f. 



92 



Stclion 11; tOMi\i;\Mj^ 



user interaction Stdin 

format: stdin var 

purpose: Pick up a newline-terminated line from the user (or stdin). 



notes: Don't use a $ unless you want the input to be placed in a variable whose name 

is the same as the content of var. stdin calls OS-9's readlnQ function. 
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strip_msb_on (strip_msb_ofl) 



socket interactions 



format: strip— msb_on socket Jiandle 
or 

strip_msb_off socket Jiandle 



purpose: 



notes: 



Cause the most significant bit (msb) of each incoming byte from a socketed 
device or process to be reset (or left unchanged). 

When chatting with a remote host computer, the most significant bit of each 
incoming byte is often used for parity checking. It is undesirable to allow the 
parity bit to come through, because when it is set, it renders the incoming byte 
uninterpretable as a character. For this reason, after socketing a device, the 
incoming data will have its most significant bit stripped unless a 
strip_msb— of f command is issued. The default situation for socketed 
processes is the reverse: the most significant bit of each incoming byte will be 
left unchanged unless a strip_msb_ on command is encountered. 
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string manipulation 



substring 



format: substring var - 

string_from__which_substringJsjto_be_copied 
starting_position ( length^oj '^substring Jto_be_copied ) 

(NOTE: as with all commands, this one must be written all on one line in the script. 
If it won't fit, use the backslash line-continuation feature [see Section 6].) 

purpose: Put a copy of a portion of a string into another variable. 



notes: 



To copy from the very beginning of the String_from_which_Substr' 
ing_isjoJbe_copied t starting__position should be 0. If length_of_jubstr- 
ingjtojbejcopied is omitted, all of the remainder of the source string will be 
copied. BEWARE: the source string must be a single token. Therefore, if it is 
a hard string (i.e., it is not given as a varname), and it has whitespace in it, 
it must be surrounded with double quotation marks. 
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switch 



flow of control 



format: switch endjabel string _to_match_with_each_case 

purpose: Executes all the code after the first matching case until a subsequent break 
is encountered. 



notes: 



This works pretty much like switch in the C language, except that each case 
is a string match rather than a value match. When the switch command is 
encountered, all the tokens after the endjabel are concatenated into a single 
string; this single string will be compared with the string given in each case. 



Remember just as in C, once a case has been matched, all the code in all 
succeeding cases will be executed until there is a break. If no case is 
matched, the code after the default, if any, will be executed. Consult a 
book on the C language for details. See also break. 

# example of a switch: 

switch 100_end_s witch $string_to_match 
case "hi mom" 

# execution resumes here if the content 

# of string_to_match is "hi mom" 
break 

case 23 

case $quodlibet 

# execution resumes here if either "23" 

# or the content of variable 

# quodlibet matches string_to_match 
break 

default 

# execution resumes here if 

# no case matches string_to_match 
1 0_encL_ swi t ch 
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debugging 

format: sys- exec of f 



sys_exec_off (sys„exec„on) 



or 



sys_exec_on 



purpose: For debugging. Disable (or enable) invocation of programs called in a script. 



notes: 



Useful in checking flow of control in scripts before allowing OJ actually to call 
any external programs. Best used with echo-on. In the absence of a 
sys— exec— of f, external program invocation is enabled. sys_exec_on 
has no effect if an --x option was used at OJ invocation time (see Section 
4). Exactly 1 token. 
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tellfile 



input/outpul 



format: tellfile file ^handle 

purpose: Find the current position of the file pointer within an open file. Sets qreturn 
to the byte number within the file, or < if there was an error. 



notes: 



Don't forget the $ before the file handle variable. By saving the the file pointer 
position in fpvar: 

tellfile $fhandle 
set fpvar = $qreturn 

you can get back to the same position by: 

seekfile $fhandle $fpvar 

See also seekfile, openfile, closefile, readfile 
writef ile, and fprintf. 
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memory management UTlSCt 

format: unset (option) varname_l (...varname__n) (option) 

options: -LOCAL 
-GLOBAL 
-LOCGLOB (both; default) 

purpose: (1) Recover the memory allocated to one or more variables by destroying the vari- 
ables altogether. 

(2) Destroy a local variable which has the same name as a global variable, so as to 
regain access to the global variable. 

notes: Using the -LOCAL option will destroy only the variables that exist in the local 

variable bank; using the -GLOBAL option will similarly restrict destruction to 
the global variable bank. Using no option (or the -LOCGLOB option) will 
destroy all matching variables in both the local and the global variable banks. 

Each variable name can include wildcards. The ? wildcard can be any single 
character; the * wildcard represents any combination of or more characters. 
To destroy all the variables, just use a *. You cannot destroy system variables. 

This command sets qreturn to E-VNOTFOUND if any of the variables 
could not be found in the designated bank(s). 
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verbose_on (verbose_off) 



socket interaction/ debugging 



format: verbose_on socket Jiandie 
or 

verbose^-off socket Jiandie 

purpose: If a verbose~on has been executed, a running status display will be sent to 
the console via siderr during each send. The status display will tell what is 
being sent, what the socketed process or device replies, how long a wait was 
required, etc. 

notes: 

When optimizing the script, set-waits should often be set to a number whictfir txuraae 
what higher AadeOriefaigtsttDuiaff^reafcapiitif tOJblkm finvokedsiwili sfawness «f)tfcm.suek- 
eted proceJsaseespamdha^Th© ajflfcciaif tejfinAsoutiWfccdnwiyhwait* j w^eoptipiiredrferto 
observe the bisjd^L^efifialHd bp flffiEKaiiflO*h«rBsainar*ett<>atfe-aDfi-w faplMfect.See Section 
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memory management/ data storage 



vrestore 



format: 
purpose: 

notes: 



vrestore filename varname^l {...varnamejn) 

Restore from the file all of the variables whose names are given. The file must 
have been made by using the vsave command. 

Each variable name can include wildcards. The ? wildcard will match any single 
character; the * wildcard represents any combination of or more characters. 
To restore all the variables in the file, just use a *. For an example, see 

vsave. 

This command sets qreturn, which must be checked if you are at all inter- 
ested in reliability. If qreturn is less than 0, the save was not done, except 
when qreturn == E-VNOTFOUND, in which case at least one variable 
was not restored because it could not be found, but the rest (if any) were restored. 
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vsave 



memory management/ data storage 



format: vsave filename (option) varname^l (...varname_n) 

purpose: Save in the file all of the variables whose names are given, for later recovery 
via the vrestore command. 



options: -NEW 



-UPDATE 
(default) 



The file, if it exists, will be completely overwritten. 

Only the named variables will be updated (and created, if neces- 
sary) within the file. This method is far more time-consuming, 
but often worthwhile. 



notes: Each variable name can include wildcards. The ? wildcard can be any single 

character, the * wildcard represents any combination of or more characters. 
To save all the variables, just use a *. System variables such as argc and 
qreturn are never saved. If you want to save their values, simply copy them 
to other variables and save those variables* 

Local variables will be saved as local variables, and they will be restored as local 
variables by vrestore. Similarly, global variables will be saved and restored 
as global variables. 

This command sets qreturn, which must be checked if you are at all inter 
ested in reliability. If qreturn is less than 0, the save was not done, except 
when qreturn == E-VNOTFOUND, in which case at least one variable 
was not saved because it could not be found, but the rest (if any) were saved. 

Example: 



vsave myvars.vs -update scores [*] donecount \ 

exam* *x* 
if (qreturn < 0) 

fprintf $stderr "vsave failed; %s\n" \ 
$e-_msg[$qreturn] 

exit 1 
endif 

In the example, a variable storage file whose name is "myvars.vs" will be created 
if it doesn't exist, or updated if it does exist. All currently extant variables which 
meet the following criteria will have their values in the file updated (if they 
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already exist) or they will be entered in the file for the first time with their 
current values): 

(1) all variables in array scores [ . . . ] 

(However, scores [whatever] [whatever_else] 
will not be saved. To save it, you might use scores*.) 

(2) variable donecount 

(3) all variables whose names begin with exam 

(4) all variables whose names contain at least one x. 
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wait 



miscellaneous 



format: 
purpose: 

notes: 



wait number _of_half_seconds (-verbose) 

Unconditionally stop further execution of the script for the number of half seconds 
given in the tag. 

Sometimes useful in auto-login scripts on systems which ignore input for some 
period of time a/ter displaying the "login:" prompt. The -verbose option 
causes a verbose-type display to appear on the console, showing the current wait 
number and the total waits. If the --v invocation option was used, it has the 
effect of adding the -verbose option to all wait commands. 
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input/output 



writefile (-writefile) 



format: writefile filejhandle string _7 ( . . . strings ) 
or 

-writefile filejhandle string J. (... string_n) 

purpose: Write some bytes on a file (or to $stdout or $stderr). 



notes: 



qreturn will be set to a negative value if an error occurred, or it will be 
set to a positive value equal to the number of bytes written. All the string tokens 
will be concatenated and written to the file. 

Don't forget the $ before the file handle variable. To output text to the screen, 
use writefile $stdout or writefile $stderr. 

writefile uses fputc(), which means that when the output is to an SCF 
device (such as /tl) rather than to a file, the translations in effect for that 
device will be done. These translations may include the expansion of tab char- 
acters into some number of spaces, and the addition of a linefeed character to 
each carriage return character. If you do not wish these translations to take place, 
use the -writefile rather than the writefile form of the command, 
-writefile calls the low-level write() function rather than fputc(); write() 
does not perform the translation. (For more information about translation of char- 
acters, consult the documentation on the x mode program in your OS-9 manual.) 

writefile is a "backslash-interpreting" command. 

See also openf ile, fprintf, closefile, readfile, seekf- 
ile, and tellf ile. It's often handier to use fprintf. 

WARNING: Once a device or file has been opened, use either writefile 
or -writefile, but do not use both. Also, if you use -writefile, 
the only other i/o command you may use with its file handle is closefile! 
Do not attempt to use fprintf, readfile, seekfile or tellf- 
ile — the results will be unpredictable. 
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Interactive Script Debugger 



The debugger is built into the OJ interpreter. It allows the programmer to control and in- 
terrupt execution of scripts at arbitrary times, and, while execution is interrupted, to examine 
the contents of any or all variables" To be in debug mode, use the --d option when invoking 
OJ. You will then see the first executable line of the script, followed by the prompt: 

OJdb: 

The line of your script which is displayed immediately above the OJdb : prompt is always 
the line which is about to be executed. 

At this prompt you may type any of the following single-letter commands (with their argu- 
ments] as appropriate), and then press the RETURN key. Each discussion of a single-letter 
command begins with a {mnemonic} word to help you remember what the letter means. 
Some effort has been made to make operation of the debugger similar to that of the OS-9 
C language source debugger, although there are (of course) numerous differences. 



{Help} 



Lists information about the debugger on the screen. 



(Shell) 



Allows temporary escape to an OS-9 shell prompt. Logging out of 
the shell will return you to where you were, at an OJdb : prompt. 
Upon returning, you may wish to use the i and/or f commands to 
see where you are. 

WARNING: It is extremely dangerous to edit any script which has 
been left open by the 1 OJ interpreter you are temporarily escaping. 
When you come back and restart execution, literally anything can 
happen, including the destruction of valuable files. Be safe: fully 
exit OJ before editing any OJ scripts; do not use this shell escape 
for editing scripts. 



(Breakpoint) Displays the breakpoints currently in effect. Breakpoints are places 

in the script, descried as "scriptname\line_number" (note the 
backslash between tro r ?ptname and the line number), where you 
wish to halt execution ard get an OJdb : prompt. If the line num- 
ber is 0, that means "halt at the first executable line." 
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b scriptname {Breakpoint} 



Sets a breakpoint at the first executable line of script scriptname. 
One arrives at such a point immediately after any do or include 
command, at the first executable line of the included or done 
script When the breakpoint is encountered, execution halts and an 
O Jdb : prompt is displayed. The actual breakpoint line number will 
be 0, which means "halt at the first executable line". 

b scriptname\linej\umber {Breakpoint} 

Sets a breakpoint at the line number given after the backslash. The 
line number must have an executable command on it, or the debugger 
will not "see" it, but will pass right over it without stopping. Exe- 
cution will halt on that line number if and only if that line is sup- 
posed to be executed/ For instance, if you put a breakpoint at a line 
which is never executed because it is in an if region whose con- 
dition is never satisfied, OJ will not halt there. 

b linejxumber {Breakpoint} 

Just like the above command, except that it stops at the line number 
within the current script. 

c calculational expression {Calc} 

Type anything here that could appear after the = token in a calc 
(or as the tokens following an if), and it will be evaluated exactly 
the same way that it would be if it occurred in a command in the 
script when the Jdb : prompt appeared. The evaluation, which is 
always a real number, will be displayed. Do not use an = sign. No 
OJ variable will be set by using this command (for that, use the si 
or sg commands). 

el {Echo-true} Turns on echo mode. This has the identical effect of an echo_on 
command or an invocation of OJ with a --e argument. 

e0 {Echo-false} Turns off echo mode. This has the identical effect of an 
echo_of f command or an invocation of OJ without a --e ar- 
gument. 

f {Frame} Displays the current "frame" or context. The current script name and 

line number are displayed first, followed by all script names and line 
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numbers containing do or include commands that led to your 
current location (the "do" stack). 

(Go} Executes the script until a breakpoint is encountered or OJ terminates. 

See the b command for information on setting breakpoints. See also 
the r debugger command. 

No echoing of lines will be done unless an echo_on command 
is/was encountered in the script, the --e option was used at OJ 
invocation time, or the el command was issued at an OJdb: 
prompt. 



g scriptname (Go) 



Execute script until scriptname is invoked by means of a do or 
include command. 



g seriptname\linej\umber {Go} 



Execute the script until line line number is encountered in script 
scriptname. The specified line must have a command on it which 
is supposed to be executed (i.e., which is not within an unsatisfied 
if region, etc.), or the debugger will not "see" it, but will pass 
right over it without stopping. 



g line number {Go} 

Execute script until line line_number is encountered in the current 
script. The line number must have a command on it which is sup- 
posed to be executed (i.e., which is not within an unsatisfied if 
region, etc.), or the debugger will not "see" it, but will pass right 
over it without stopping. 

NOTE: All of the above argumented g ("go until...") commands ac- 
tually set a temporary breakpoint which goes away as soon as it is 
first encountered. In other words, the breakpoint set with an 
argumented g command only works once. To set a breakpoint that 
is not unset when it is encountered, use the b command. 

i (Info) Redisplays the line you are about to execute. 
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k b breakpoint number {Kill} 



Kills a breakpoint previously created by the b command. First, do 
a b command with no argument; this will show all the breakpoints. 
The breakpoints are identified as bO, bl, b2, etc. Decide which one 
you want to kill, and enter its name (e.g., bO) as the argument of 
a k command: 

OJdb: k bO 



{Kill} 



Kills all breakpoints. 



{List} 



Displays a numbered-line listing of the current script, starting at the 
current line in that script, one screen at a time. If all the script file 
has not yet been sho?vn, the prompt will be: 

OJdb [LIST] : 
In order to see the next screenful of text, press RETURN. 



1 linejxumber {List} 



Like 1, above, except the listing will begin with the line number 
given in the argument. 



1 textjxlename {List} 



Like 1, above, except that you will be looking at any arbitrary text 
file whose name you give in the argument. This of course includes 
scripts other than the one you are presently executing. 



1 text J\lej\ame\line number {List} 



n 



{Next} 



Displays the named text file, starting at the specified line number. 
Be sure to use a backslash between the two arguments. 

Executes the script line already displayed above the prompt, shows 
the next line to be executed, and gives another OJdb: prompt. 
When you press n the first time, the OJdb: prompt becomes 
OJdb [NEXT] :. This means that you don't have to press n fol- 
lowed by RETURN to repeat the n command; instead, just press 
RETURN all by itself. 
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n number {Next} Executes the specified number of lines in the script, echoing each of 
them before execution; it's equivalent to issuing the n command that 
number of times. 

p variablejiame {Print} 

Displays the contents of the variable named in the argument. You 
may use wildcard characters (?, *) in the variable names to see sev- 
eral variables at once. An asterisk all by itself will display all vari- 
ables. 

q {Quit} Aborts execution of OJ and returns you to your original shell prompt. 

r {Return} Executes the remainder of the current script, halting automatically 

when you return to the calling script. 

si varjojet = strings... (Set Local} 

Set a local variable to some string value. See sg below. 

sg varjoset = strings... {Set Global} 

Set a global variable to some string value. The si and sg com- 
mands behave identically to the set command, except that you can 
be specific about whether you wish to set a local or a global variable. 
WARNING: These debugging commands have no impact on the script 
itself except during the current debugging session; the script itself 
still has to be fixed. 
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Errors 



These are the names of the pseudo-variables containing the values returnable by qreturn, 
together with their actual numeric values and the strings found in the 
e__msg[$qreturn] array. WARNING: Don't use the values; use the names instead. 
The values may change, but the names won't. 



$E_NO_ERR 





$E_FOPEN 


-1 


$E_NONINT 


-2 


$E_BADPLC 


-3 


$E_BADSEEK 


-4 


$E_BADTELL 


-5 


$E_PSWENTAWAY 


-6 


$E_PSJUSTDIED 


-7 



$E_PSNOFORK 
$E_INVSOCKH 



■8 
-9 



no reportable error has occurred 



file could not be opened via fopen() 



an integer value was required; this 
wasn't an 'integer 

place value for seek{) was not 0, 
1, or 2 

fseek() failed 



ftell() failed 



process already was dead 



process just died; normal after a 
regular OS-9 invocation; if a 
socketed process, another socket is 
now required 

process ;oulc not be forked at all 



invalid socket handle 



$E_INVFH 



10 invalid file handle 
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$E_BADCHD -11 

$E_BADCHX -12 

$ E_C VCHTOOMANY - 1 3 

$ E_BADCONVSTR - 1 4 

$ E_CVCHTOOFEW - 1 5 

$E_RFEOF -16 

$E_NOTVFILE -17 

$E_CORRVFILE -18 

$E_VF_NO„WRITE - 1 9 

$ E_VNOTFOUND - 2 



unsuccessful attempt to change data 
directory 

unsuccessful attempt to change 
execution directory 

more %'s in control string than 
arguments 

conversion string beginning with % 
is ill-formed 

fewer %'s in control string than 
arguments 



/ 
file is exhausted 
available 



no more data 



file exists but is not a variable 
storage file 

existing variable storage file is 
corrupt 

could not write variable storage 
file 

while saving, restoring, or 
unsetting variables, at least one 
requested variable did not exist 
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INVOCATION OPTIONS 

-? 7 

--b 7 

— d 7 

--e 7 

— q 7 

--v 7 

--x 8 



FUNCTIONS USED IN CALCULATIONAL EXPRESSIONS 

charval (a) 22 

devrdy (device name) 22 

frac(va/) 22 

g va r num ( varname ) 23 

hex2dec(va/) 23 

index (pattern s [start]) 23 

int (val) 23 

isdir(patft) 23 

is file (path) 24 

isreal (string) 24 

length (var) 24 

1 va mum ( varname ) 24 

max (varname varname) 24 

min (varname varname) 24 

namecmp (target pattern) 24 

oct2dec(Vfl/) 24 

rand ( ) 24 

strcmp(a b) 24 
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OJ COMMANDS 

CALCULATION 

calc resultvarname = caicjexprzsshn 38 

DATA STORAGE 

vrestore filename yarname_l {..yarnameji) 100 

vsave filename (option) vamamej (..yarnameji) 101 

DEBUGGING 

echo_on 

echo_off 48 

debug_on 

debug_off 44 

show_coml ines_on 

show__comlines_of f 82 

show„labels 83 

show_jnbfs socket handle 84 

show_tokens_on 

show_tokens_ of f 85 

show_vars 86 

sys_ exec_of f 

sys_exec„on 96 

verbose_on socket _handle 

verbose off socket handle 99 



EXTERNAL PROCESS CONTROL 

any JDS-9 program Jnvocationjxame 3 1 

redirect stdin varname 69 

s e t_pr i or calc expression yielding _processj>riority_yalue 78 

FLOW OF CONTROL 

break 37 

case 39 

continue 43 

default 45 

do O J script name (arg_l...arg_n) 47 

else 49 
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50 



57 
59 



endif 

exi t ( calcjxpression ) 5 j 

goto label 53 

if calculational expression 54 

include oj script jxame 55 

istop 

istart 

label 

loop end label ; (i nit jar = initialization jalcjxp) ; \ 

(testjaTcjxp) ; (increm_var = incrementing _calc_exp) 62 

oj ojjcriptjiame (argj...argji) 54 

return ( calculational ^expression) 7 1 

switch end label string Jo jnatch_with each case 95 

INPUT/OUTPUT 

ciosefile filejiandle 42 

fprintf filejiandle control jtring {string 1... string ji) 52 

openf ile varjorjilejandle = filejiame action 65 

readf ile filejiandle varjorjinejromjile 68 

seekf ile filejiandle offset place 72 

tellfile filejiandle 97 

writefile filejiandle string J (...stringji) 104 

MEMORY MANAGEMENT 

local varnamej (...vamameji) 60 
unset (option) varnamej (...vamameji) (option) 

options: -LOCAL, -GLOBAL, -LOCGLOB (both; default) 98 

vrestore filename varnamej (...vamameji) 100 
vsave filename (option) varnamej (...vamameji) 

options: NEW or UPDATE 10 1 

MISCELLANEOUS 

cd directory Jo Jbecome current jiatajlirectory 

chd directory to _become_currentjdatajtirectory 40 

chx directory jo Jbecome jurrentjxecutionjiirectory 41 

wait number j)fJialf_seconds 10 3 
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STRING MANIPULATION 



55 
66 



RANDOM NUMBERS 

randlist arrayname arraysize lowest possible value 
number of _possible_values (option) 

options: UNIQUE (default) or REPEATABLE 67 

set rand seed string _ 9 

SOCKET INTERACTION 

ignore socket handle 
password 
password = string 
send socket Jiandle = \ 

var to receive_namej>f matched Juffer string 1 (...string n) 73 

set_mbf socket handle name of buffer Joset \ 
type ofmatcF to make = stringl (...string n) 

(use with BEGIN, END, or EXACT type of match ) 
set_mbf socket handle nameofbuffertoset \ ~ ~ 

B&E token juedju a separator = string 1 (...string n) \ 
stringo (...strlhg_p) ~ 6 ~ 

(use with B&E typeof match...) 76 

set_send_delay socket handle integer value 
set_waits socket handle integer _value 
show_mbfs socketjiandle 
socket varjorjocket Jiandle = device name 
socket varjorjocket Jiandle = pipejlzejn bytes \ 

process jxame (process arg 1... process are n) 
socket socketjiandle ~ ~ 

strip_msb_on socketjiandle 
strip_msb_off socketjiandle 
verbose_on sockethandle 
verbose_of f socket handle 



80 
81 

84 



87 
93 
99 



32 



alphameric vartoset = string 1 (...stringji) 
arraytok separator _character(s) arrayname '(option) \ 

string J (...stringji) 

options: -GOBBLE or -NOGOBBLE (default) 33 

bits var = decimal integer 
replace code: S_or C char(s) to replace \ 

what to replace tfiemwith output var = string 1 (...string n) 



36 
70 
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set resultvar = (ULR) string J (... string ji) options: U , L , R , or 

none *}* 

sort source array sorted jarray (reverse) 88 

sprint f varjojbejet control jtring {string L ..string _n) 91 

substring var = string Jromjvhichjubstringjs Jo becopied \ 

startingj)osition (length _of _subst ring Jo _be_copieI) 94 

TIME MEASUREMENT 

difftime target _yarname = marktime value 1 marktime_value_2 46 
Julian varjorday number varjorjecondjxumber \ 

varjor tickjiumSer varjorjicks-per-secondjyalue \ 

= marBime value 
mark time varname 63 

USER INTERACTION 



58 



spiiidev device 90 

stdin var g 2 



119 



QUICK REFERENCE 



This page deliberately left blank, 



120 



Index 



t 



! redirection operalor...33, 74 
!■ ...22 
" ...9, 31 

# comment begin delimiter...l3, 31, 60 

# not comment begin delimiter 34 
$ ...15-19,74,117-118 

$ (Shell}...lll 

$ variable substitution... 10 - 11, 15 - 17, 21 

31, 41, 45, 73 - 74, 77, 97, 102, 109 
% ...118 
% (modulus)...21 
% conversion...9, 17, 37 
% modulus...24, 118 
& ...69 
&&...22 
' ...23 

* (multiply).„21 

* wildcard..^!, 103, 105 - 107, 115 
+ (add). ..21 

- (subtract)...21 

- dash...33 - 34 

- minus.„16 

- single hyphen...5 
-- ...69 

- double hyphen...7 
-? ...7 

-GOBBLE...38 
-verbose ...108 
-writefile...l09 
-writefile command...!09 

. (dot)... 10, 15, 61, 63, 84, 108 
/ (divide)...21 

< less than...21 

< redirection operator..33, 74 

...21 
= ...80-81,112 
= (assignment operator)..21 



== ...21 
=L ...80 
=R ...32, 35, 80 
=U ...80 

> (greater than)..21 

> redirection operator...33 74 
= ...21 

» redirection operator...33, 74 

? (Help). ..6, 111 

? wildcard...24, 103, 105 - 106, 115 

\ in breakpoint...lll 

\ line continuation.„10 

] ...10 

_ ...10, 63 

II ...22 



a ...70 

a+ ...70 

abort...9 - 11, 18, 29, 33, 50, 72 - 73, 115 

accuracy...49, 68 

action. ..70 

add (+)..2l 

addressable...92 

algorithms...49 

alphabetical...l0, 23 - 24, 63, 94 

alphameric.2, 35, 80 

alphameric command...35 

AND (&&).. 22 

3"»swer...5 

any_OS~9j>ragramJnvocation name. 29 
33, 69, 74 

append...69 - 70 

argc.2, 29, 50, 59, 64 - 65, 106 

argument...l, 7, 9 - 10, 21 - 22, 29, 34, 50, 59, 

65,69,72,76,111- 115,118 
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argv.„2, 29, 50, 59, 64 - 65 

arithmetic..^, 16 

array...2, 10, 16 - 19, 23 - 24, 28 - 29, 36, 72, 

93, 107, 117 
arraytok...2, 36 - 38 
arraytok command„.36 
ASCII...22 

assignment„.10, 16, 21 
associative...l 
asterisk... 115 
auto-login...l08 
awk...l 



B 



-b ...7 

b { Breakpoint }...l 11 - 114 

background...69 

backslash...2, 9, 11, 13, 19, 22, 31, 34 - 36, 38, 

49, 55, 61, 66, 72, 75, 78 - 82, 92, 96, 99, 

109, 111 - 112, 114 
BACKSLASH-INTERPRETING 

COMMANDS...31 
backspace...31 
banner ...2, 27 - 28, 106, 117 
BAT...1 
batch files...l 
bit ...39, 98 
bits ...98 

bits command...39 
brackets...lO, 17 - 18 
break... 1, 13, 40, 66, 100 
break command...40 
breakpoints, 47, 111-114 
buffer...3, 7, 45, 78, 81 - 82, 86, 89 
buffer size...7 
byte...7, 23, 31, 35, 58, 73, 77, 84 - 86, 88, 92, 

98, 102, 109 
bytes...95 



c {Calc}...112 

C-language...l - 2, 31, 51, 55, 61, 66, 75, 96, 

100, 111 
C-Shell...l 
calc command. ..41 
calculation..^, 15 - 16, 18 - 19, 21 - 23, 41, 54, 

57,66,76,83, 112 
CALCULATIONAL EXPRESSIONS..^ 
CALCULATIONS, VARIABLES 

AND FUNCTIONS. .2 
calendar...61 
call...l, 6, 11, 18, 27, 29, 50 - 51, 59, 64 - 65, 

69,74,76,97, 101, 115 
cancel...56, 89 
capitalize...65 

carriage return character.,.109 
case...40 

case command...42 
cd ...43 

cd, chd command...43 
CD-RTOS...1 
character.,.9 - 11, 13, 15 - 16, 19, 22 - 24, 31, 

34, 36, 38, 41, 60, 63, 68, 75, 80, 98, 103, 

105 - 106, 115 
characters ...22 
charval()..2, 22 
chat...l, 98 
chd ...3, 5,43 
chdir...43 
chronological...61 
chx...3, 44 
chx command...44 
chxdir...44 
class..2, 11, 17,64 
clearing. ..95 
clock...61, 68 
close...45 

closefile..2, 45, 55, 70, 73, 77, 102, 109 
closefile command..,45 
combine...l0, 22, 61, 103, 105 - 106 
command-specific.l 1 
COMMANDS..33 
COMMENTS ...13, 31, 34, 60 
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compare...21, 24, 27, 78, 82, 100 
concatenation...^, 33, 36, 75, 78, 80 - 82, 100, 
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